Slate Docs ile Api Dökümantasyonu Oluşturmak

Merhaba arkadaşlar,

Bu yazımda her şirkette yada her projede olmazsa olmaz dökümantasyon konusuna değinmek istiyorum. SlateDocs adlı açık kaynak bir proje ile mardown olarak yada backend projenizin swagger dökümantasyonu varsa ufak bir toolla kısa yoldan nasıl bir dökümantasyon çıkarabilirsiniz onu gösteriyor olacağım

Yüklenmesi Gerekli Olanlar

• Docker
• Git
• Ruby (Macos kullanıyorsanız XCode yüklemesi ile geliyor direk olarak)
• NodeJs => https://nodejs.org/en/ (Mac kullanıcısı iseniz Homebrew üzerinden => brew install node)
• Slate reposundan fork edilmiş repo => https://github.com/slatedocs/slate
• Herhangi bir OpenAPI/ Swagger yaml dosyası yada json dosyası (Opsiyonel)

Slate Docs Kurulumu

1. İlk olarak slate reposuna gidip fork alınız

2. Terminal uygulamınızdan;

git clone https://github.com/<your_github_username>/slate.git

3. Clone işlemi tamamlandıktan sonra içeride slate adlı bir klasor olacaktır. Herhangi bir text editor ile /slate/source/index.html.md yolundaki dosyayı açarak dökümanınızı hazırlayabilirsiniz (Markdown nasıl yazılır öğrenmek için => https://guides.github.com/features/mastering-markdown/)

4. Şimdi neler yaptığımızı görmek istiyoruz arkadaş ne yaptığımı nasıl göreceğim dediğiniz ana geldik 😀 Onun için;

• DockerFile

FROM ruby:2.6-slim

WORKDIR /srv/slate

VOLUME /usr/src/app/source
EXPOSE 4567

COPY . /srv/slate

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
        build-essential \
        nodejs \
    && gem install bundler \
    && bundle install \
    && apt-get remove -y build-essential \
    && apt-get autoremove -y \
    && rm -rf /var/lib/apt/lists/*

CMD ["bundle", "exec", "middleman", "server", "--watcher-force-polling"]

• docker-compose.yaml adlı dosya yaratın.

app:
  build: .
  ports:
    - 4567:4567
  volumes:
    - ./source:/usr/src/app/source

Terminal üzerinden slate clone olan dosyanın içinde (bu süreç ilk seferinde uzun sürebiliyor bilginize)

docker-compose up

Browserda localhost:4567 adresize gidiniz.

Kod tarafında değişiklik yapıp değişiklikleri görmek için aşağıda ki komutu çalıştırıp localhost:4567 adresinde görebilirsiniz

docker-compose up --build

Ben visual studio code kullanıyorum text editor olarak orada extensions tarafında kurmanızı tavsiye edeceğim eklenti (Bu sayede önizleme yapabilirsiniz aşağıdaki görsel gibi) => https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one

Şimdi şöyle bir yorum yapabilirsiniz bizim swagger dosyamız var ondan direk slate dökümantasyonunu yapabilir miyiz?

Sorunuzun yanıtı direk olarak evet 🙂 Bunun için güzel bir npm paketi var => https://www.npmjs.com/package/swagger-to-slate

• Nodejs yüklü olduğundan emin olduktan sonra terminalde yükleyiniz

npm i -g swagger-to-slate

Örnek olarak misal elinizde projelerden birinde yaml yada json dosyası olsun o lokasyona gidip yada örnek json dosyası buradan alabilirsiniz;

swagger-to-slate -i petstore.yaml

Sonrasında size markdown üretmiş olacak, projenizin içinde ki index.html.md yi burada üretilen yeni içerikle değiştirin ve ismini index.html.md olarak kaydedin, artık swagger üzerinden üretilmiş slate dökümanınız hazırdır.

Blog yazısının ve örneğin reposu ==> https://github.com/yalcinumutt/slate-api-dokumantasyon

Sorularınız için yorumlarda yada direk iletişim kurmak isterseniz mail adresim ==> yalcin.umutali@gmail.com

Yakın zamanda Docker üzerinde bir yazı serisi başlatmayı düşünüyorum yakında gelecek yazılar 🙂

İnşallah katkısı olması dileğiyle, teşekkürler okuduğunuz için.