Swagger belirtimi JSON'yi HTML belgelerine dönüştürme

90

PHP'de yazılan bazı REST API'leri için Swagger dokümantasyonu oluşturmam istendi ve bu mevcut API'lere ek açıklamalar eklemenin ve böyle bir dokümantasyon oluşturmanın kolay bir yolunu bilmediğim için, şimdilik bazılarını oluşturmak için bu düzenleyiciyi kullandım .

Bu düzenleyiciyi kullanarak oluşturulan JSON ve YAML dosyalarını kaydettim ve şimdi son etkileşimli Swagger belgelerini oluşturmam gerekiyor (bu ifade saf ve belirsiz gelebilir).

Birisi Swagger JSON belirtim dosyasını gerçek Swagger belgelerine nasıl dönüştürebileceğimi bana bildirebilir mi?

Windows platformundayım ve Ant / Maven hakkında hiçbir şey bilmiyorum.

yaml swagger swagger-php

— Salil
kaynak

[ github.com/wordnik/swagger-ui](Swagger UI) denedim ama json'umu oluşturmuyor. gösterilen tek uyarı "Bu API, Swagger'ın kullanımdan kaldırılmış bir sürümünü kullanıyor! Daha fazla bilgi için lütfen github.com/wordnik/swagger-core/wiki'ye bakın " şeklindedir.

— Salil

43

Bunu swagger-codegenyapacak bir araç ararken tatmin olmadım, bu yüzden kendim yazdım. Bootprint-swagger'a bir göz atın

swagger-codegenİle karşılaştırıldığında asıl amaç kolay bir kurulum sağlamaktır (nodej'lere ihtiyacınız olacak olsa da). Ve bu bir temel işlevi olan kendi ihtiyaçlarına stil ve şablonları uyarlamak kolay olmalıdır bootprint -Proje

— Nils Knappmeier
kaynak

9

Uyarı: 11/2016 itibariyle bootprint-swagger'ın yazarı görünüşe göre projeyi terk etti. swagger-codegen hala iyi destekleniyor.

— Brent Matzelle

22

Yazar benim ve metin şöyle diyor: "Bu proje için yakın gelecekte yeni özellikler geliştiremeyeceğimi söylediğim için üzgünüm. Ancak: Muhtemelen çekme isteklerini tartışabilir ve birleştirebilirim, ve yeni sürümler yayınlamak. " Buna terk edilmiş diyebilirsiniz, ben buna "beklemede" derim. Projeye katkıda bulunmak isteyen herkesi de davet edeceğim.

— Nils Knappmeier

1

spectacleSwagger JSON'dan çok daha iyi görünümlü belgeler üreten bulundu

— eternalthinker

61

Redoc-cli kullanmayı deneyin .

Kullanıyordum bootprint-OpenAPI (ki I dosyaların bir demet üreten edildi bundle.js, bundle.js.map, index.html,main.css ve main.css.map) ve daha sonra tek bir dönüştürebilir .htmlkullanarak dosyanın html-inline basit oluşturmak için index.htmldosyayı.

Sonra buldum redoc-cli'yi kullanmanın çok kolay olduğunu gördüm ve çıktı gerçekten-2 harika, tek ve güzel bir index.html dosyası.

Kurulum :

npm install -g redoc-cli

Kullanım :

redoc-cli bundle -o index.html swagger.json

— Vikasdeep Singh
kaynak

8

Bu araç, bahsedilen tüm araçların gerçekten en güzel çıktısını yapar.

— Jakub Moravec

Oluşturulan hepsi bir arada HTML dosyası oldukça büyük. Özel HTML'den canlı oluşturma durumunda JS kitaplığı bağımlılığı (~ 800KB) de öyle. Boyutun nasıl küçültülebileceğini bilen var mı?

— aaronqli

1

Bu, açık ara en iyisi ve bunu masaüstü kullanan geliştiriciler için oluşturduğumuzdan, çıktı boyutu sorun değil.

— milosmns

3

Doğrudan yürütülebilir adın kullanılması her zaman işe yaramaz, yürütme npx redoc-cli ...daha güvenilirdir.

— Crouching Kitten

21

Ben basit bir komut dosyası ile bu çözüldü yüzden her şey çok zor ya da kötü bir şekilde belgelenmiş oldu swagger-yaml-to-html.py bu gibi çalışır,

python swagger-yaml-to-html.py < /path/to/api.yaml > doc.html

Bu YAML içindir, ancak onu JSON ile çalışacak şekilde değiştirmek de önemsizdir.

— Oseiskar
kaynak

Ayrıca artık liman işçisi olarak da mevcut! github.com/yousan/swagger-yaml-to-html

— noamtm

19

Pretty-Swag'a göz atın

Var

Swagger-Editor ile benzer görünüm sağ paneline
Ara / Filtrele
Şema Katlama
Canlı Geribildirim
Tek bir html dosyası olarak çıktı alın

Swagger Editor'a bakıyordum ve önizleme bölmesini dışa aktarabileceğini düşündüm, ancak yapamayacağı ortaya çıktı. Ben de kendi versiyonumu yazdım.

Tam Açıklama: Aracın yazarıyım.

— TLJ
kaynak

1

Uygun CLI ve API giriş noktaları ile oldukça gösterişli ve ideal bir araç olduğunu gördüm. Benim tek ve tek şikayetim (ve beni bunun yerine swagger-ui'nin karmaşıklığıyla uğraşmaya zorlayan), nesne kompozisyonunu / uzantısını doğru şekilde ele alamamasıydı. allOfBelgede öğesinin herhangi bir şekilde kullanılması, undefineden basit senaryolarda bile (tek bir nesnenin "birleştirilmesi", hiç kullanılmamasına eşdeğer) üretir allOf.

— HonoredMule

3

Sadece allOfsizin için kullanıma sunulmuş bir özellik. Bunu kontrol et.

— TLJ

2

Swagger / OpenAPI V3

— SeinopSys'i

16

Bkz çalım-api / dayı-codegen GitHub'dan projeyi; README projesi, statik HTML oluşturmak için nasıl kullanılacağını gösterir. Statik html api belgeleri oluşturma konusuna bakın .

Swagger.json dosyasını görüntülemek istiyorsanız Swagger kullanıcı arayüzünü kurabilir ve çalıştırabilirsiniz. Sadece bir web sunucusuna (depoyu GitHub'dan klonladıktan sonra dağıtım klasörü) konuşlandırın ve Tarayıcınızda Swagger kullanıcı arayüzünü görüntüleyin. Bu bir JavaScript uygulaması.

— djb
kaynak

Teşekkürler. Benim sorunum, swagger-ui'nin 2.0 spesifikasyonunu kabul etmemesiydi. Ancak, bu en basit cevap gibi görünüyor, bu yüzden bunu (şimdilik) kabul edeceğim.

— Salil

Swagger araçları hala 2.0 için evrim geçiriyor. Ancak, Swagger UI'nin "swagger": "2.0" ile başlayan 2.0 dosyalarım için çalıştığını buldum

— djb

Ayrıca, Swagger Düzenleyiciden JSON spesifikasyonunu dışa aktarabilirsiniz (YAML olarak değil JSON olarak) ve Swagger UI bunu okuyabilmelidir. (Not: swagger.json, Swagger UI uygulamasıyla aynı ana bilgisayarda / bağlantı noktasında olmalıdır veya CORS'u etkinleştirmeniz gerekir; GitHub'daki Swagger Düzenleyicisinde README.md'ye bakın

— djb

14

Çok zaman harcadım ve birçok farklı çözüm denedim - sonunda şu şekilde yaptım:

<html>
    <head>    
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@3.17.0/swagger-ui.css">
        <script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
        <script>

            function render() {
                var ui = SwaggerUIBundle({
                    url:  `path/to/my/swagger.yaml`,
                    dom_id: '#swagger-ui',
                    presets: [
                        SwaggerUIBundle.presets.apis,
                        SwaggerUIBundle.SwaggerUIStandalonePreset
                    ]
                });
            }

        </script>
    </head>

    <body onload="render()">
        <div id="swagger-ui"></div>
    </body>
</html>

Sadece / to / my / swagger.yaml dosyasının aynı konumdan sunulması gerekir .
(veya CORS başlıklarını kullanın)

— Kris Randall
kaynak

Harika, teşekkürler! <Link rel = "stylesheet" href = " Petstore.swagger.io/swagger-ui.css "> <script src = " Petstore.swagger.io/swagger-ui-bundle.js "></script > kullandım

— Erando

7

Swagger kullanıcı arayüzünü şu adresten de indirebilirsiniz: https://github.com/swagger-api/swagger-ui , dist klasörünü alın, index.html'yi değiştirin: yapıcıyı değiştirin

const ui = SwaggerUIBundle({
    url: ...,

içine

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

şimdi dist klasörü ihtiyacınız olan her şeyi içerir ve olduğu gibi dağıtılabilir

— user1928596
kaynak

2

Şu bağlantıya bir göz atın: http://zircote.com/swagger-php/installation.html

Phar dosyasını indirin https://github.com/zircote/swagger-php/blob/master/swagger.phar
Composer'ı yükleyin https://getcomposer.org/download/
Composer.json oluşturun
Swagger-php / kitaplığı klonla
Swagger-ui / kitaplığı klonla
API için Kaynak ve Model php sınıfları oluşturun
Json'u oluşturmak için PHP dosyasını çalıştırın
Api-doc.json'da json yolunu verin
Api-doc.json dosyasının yolunu index.php içinde swagger-ui dist klasörü içinde verin

Başka bir yardıma ihtiyacınız olursa lütfen çekinmeden sorun.

— Syed Raza Mehdi
kaynak

1

Bunu benim için oluşturabilecek çevrimiçi bir editör (swagger-editor dışında) var mı? Daha basit bir yolu varsa PHP API'lerime açıklama eklemek istemiyorum. Anladığım sorun, swagger-editor'ün swagger spec v2.0'ı oluşturması ve swagger-ui'nin şu anda bunu işlememesi.

— Salil

@Salil tek bildiğim, swagger'ın kendi çevrimiçi düzenleyicisini sağladığı, yani editor.swagger.wordnik.com Başka bir çevrimiçi editörden haberdar değilim, eğer bizimle paylaşırsanız, teşekkürler :)

— Syed Raza Mehdi

2

Bir yaml dosyasından belgeler (adoc veya md) oluşturan küçük bir Java programı var.

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
        .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .withSwaggerMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .withOutputLanguage(Language.DE)
        .build();

Swagger2MarkupConverter builder = Swagger2MarkupConverter.from(yamlFileAsString).withConfig(config).build();
return builder.toFileWithoutExtension(outFile);

Ne yazık ki yalnızca OpenAPI 2.0'ı destekler, ancak OpenAPI 3.0'ı desteklemez .

— Erando
kaynak

2

Swagger API 3.0 için, çevrimiçi Swagger Editor'dan Html2 istemci kodu oluşturmak benim için harika çalışıyor!

— Kumar S
kaynak