Slate - Swagger - Hangisi daha iyi ve daha fazla seçenek var?

Question

API'larımı belgelemem gerekiyor. Bunlardan herhangi birini Slate veya Swagger kullanmam gerekiyor. Hangisinin daha iyi seçenek, artı ve eksileri olduğunu bilmek istiyorum.

Answer 1

Swagger ve Slate iki farklı amaca hizmet eder. Havalı (ApiBlueprint örneğin, benzer şekilde,), dinlendirici bir API tarif standart bir şekilde bir girişim

Havalı REST API açıklaması için izin veren bir JSON tabanlı bir API tanımlı format, olmasıdır.

~ API Design Tooling From Swagger

Slate, diğer taraftan güzel API docs yazma için oldukça tema.

1. iki
2. İdeal birbirini dışlayan değil, kimse Swagger API açıklaması

Swagger hedefi diğerleri geniş takım oluşturabilir bunun üzerine bir standart sağlamaktır adresinin kayrak belgeleri oluşturmak gerekir (örneğin: belgeler, API kaşifleri, sahte sunucular, kod oluşturma, test yardımcı programları vb.). Örnek için bakınız: Swagger Tooling

Daha sorunuza: Bazı Slate takım havalı için:

İşte

• İşte link to a Slate themed swagger UI
• olduğunu generates Slate docs based on your Swagger definition

Yani ikisi bir projedir Karşılıklı olarak değil, doğrudan sorunuzu yanıtlayın: Swagger'ı uygulamak size daha fazla seçenek ve daha fazla esneklik sağlayacaktır (ayrıca Slate belgelerini de üretme kabiliyetine sahipti).

Answer 2

Benim bakış açıma göre, bu araçların çok farklı amaçları vardır. Kaydırmak sadece dokümantasyon için iken, Swagger bir açıklama dilidir.

API'm için farklı istemcileri otomatik olarak oluşturabildiğim bir descriptionn oluşturmak için swagger kullanıyorum, hatta belgeleri otomatikleştirin.

Ayrıca, swagger özelliklerinden Markdown'ı da yaratabilirsiniz ve bu yazımları Slate'de kullanabilirsiniz. [1]

[1] https://github.com/RobWin/swagger2markup

Slate Hakkında

Answer 3

:
- API belgeleri Şablon/Çerçeve
- iyi görünüyor
- kullanım
kolaylığı - Dil Özgül - Sözdizimi
vurgulama - Sekmeli
- Page Search
- 3 sütunlu özelleştirilebilir düzen
- Tablo oluşturabiliriz
- kaydırılabilir her bağlantıları ve her blok/yöntem/başlıkları
- Uyarı Tesisi [3 tip] - Uyarı, başarı, ihbar
- http hata kodları için masalar
- Markdown sözdizimi
- Biz Sitesi logosunu
kullanabilirsiniz - Swagger Hakkında Demo

:
- O bize herhangi bir istek için tepkisini kontrol edebilirsiniz docs kendisinin içinde API erişim sağlar.
- API'nin parametreleri ve seçenekleriyle ilgili net bir görüntüsünü verir. - YAML tabanlı biçim
- hypermedia API
için uygun değil - Swagger
için herhangi Tasarım takım var - Swagger JS - - tarayıcı üzerinden swagger özellikli API'ler bağlanmak için JavaScript kütüphanesi Yanıtları XML veya JSON
içindedir Swagger Düğüm Express - - node.js ekspres modül
için Swagger modülü - ya
nodejs piton-balona dayalı Demo

Answer 4

Ben barut şişeyi (https://github.com/AhnSeongHyun/slate-flask) yapmak - Bu swagger UI çerçeve
sahiptir.

özellikleri:

• Yapılandırma Dosyası (config.json): Set başlığını, JSON Format üzerinde config.json tabanını kullanarak örnek kodları için programlama dili. Ayrıca, API belgelerinin ve TOC'nin (İçindekiler) yolunu da ayarlayın.

• Çoklu API belgelerini destekler: Orijinal Slate, Markdown biçimine dayalı bir API belgesini destekler.Ancak, arduvaz, verimli yönetim ve TOC (index.json) kullanan dokümanların miktarı için çoklu API belgelerini destekler.

• Belgelerin dinamik değişikliklerini destekleyin: Sunucuyu yeniden başlatmadan API belgelerinin değişikliklerini yansıtabilirsiniz. Web sayfası yenilendiğinde, değişiklikler varsa, arduvaz kaplaması API belgelerini yeniden yükler. Kullanıcılar sadece API belgelerini yazmaya odaklanır.