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
- İlk olarak slate reposuna gidip fork alınız
![](https://umutyalcin.files.wordpress.com/2020/09/slate1.png?w=1024&resize=585%2C244)
2. Terminal uygulamınızdan;
git clone https://github.com/<your_github_username>/slate.git
![](https://umutyalcin.files.wordpress.com/2020/09/slate2.png?w=1200)
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/)
![](https://umutyalcin.files.wordpress.com/2020/09/slate3.png?w=1200)
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
![](https://umutyalcin.files.wordpress.com/2020/09/slate4.png?w=1200)
Browserda localhost:4567 adresize gidiniz.
![](https://umutyalcin.files.wordpress.com/2020/09/slate5.png?w=1200)
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
![](https://umutyalcin.files.wordpress.com/2020/09/slate6.png?w=1200)
Ş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.
Good way of explaining, and pleasant article to
get information about my presentation focus, which i am going
to convey in college.