Conversione della specifica JSON di Swagger in documentazione HTML

90

Per alcune API REST scritte in PHP, mi è stato chiesto di creare documentazione Swagger e, poiché non ero a conoscenza di alcun modo semplice per aggiungere annotazioni a quelle API esistenti e creare tale documentazione, ho usato questo editor per generarne alcune per ora.

Ho salvato i file JSON e YAML creati utilizzando quell'editor e ora ho bisogno di creare la documentazione interattiva finale di Swagger (questa affermazione potrebbe suonare ingenua e vaga).

Qualcuno può farmi sapere come posso convertire il file delle specifiche JSON di Swagger nella documentazione effettiva di Swagger?

Sono sulla piattaforma Windows e non so nulla di Ant / Maven.

yaml swagger swagger-php

— Salil
fonte

ho provato [ github.com/wordnik/swagger-ui”(Swagger UI) ma non rende il mio json. l'unico avviso mostrato è "Questa API sta utilizzando una versione deprecata di Swagger! Per maggiori informazioni, visita github.com/wordnik/swagger-core/wiki ".

— Salil

43

Non ero soddisfatto swagger-codegenquando cercavo uno strumento per farlo, quindi ho scritto il mio. Dai un'occhiata a bootprint-swagger

L'obiettivo principale rispetto a swagger-codegenè fornire una configurazione semplice (anche se avrai bisogno di nodejs). E dovrebbe essere facile da adattare stile e modelli per le proprie esigenze, che è una funzionalità di base del bootprint -project

— Nils Knappmeier
fonte

9

Attenzione: dall'11 / 2016 l'autore di bootprint-swagger ha apparentemente abbandonato il progetto. swagger-codegen è ancora ben supportato.

— Brent Matzelle

22

Sono l'autore e il testo dice: "Mi dispiace dover dire che non sarò in grado di sviluppare nuove funzionalità per questo progetto nel prossimo futuro. Ma: probabilmente sarò in grado di discutere e unire richieste pull, e per pubblicare nuove versioni ". Potresti chiamarlo abbandonato, io lo chiamerei "in attesa". Inviterò anche chiunque sia interessato a contribuire al progetto.

— Nils Knappmeier

1

Trovato che spectaclegenera una documentazione molto più bella dal JSON

— spavaldo

61

Prova a usare redoc-cli .

Stavo usando bootprint-OpenAPI con cui mi è stato la generazione di un gruppo di file ( bundle.js, bundle.js.map, index.html, main.csse main.css.map) e poi è possibile convertirlo in un singolo .htmlfile utilizzando html-inline per generare un semplice index.htmlfile.

Poi ho trovato redoc-cli molto facile da usare e l'output è davvero 2 fantastico, un unico e bellissimo file index.html .

Installazione :

npm install -g redoc-cli

Utilizzo :

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

— Vikasdeep Singh
fonte

8

Questo strumento rende davvero l'output più bello di tutti gli strumenti menzionati.

— Jakub Moravec

Il file HTML all-in-one generato è abbastanza grande. Così è la dipendenza della libreria JS (~ 800KB) nel caso del rendering dal vivo da HTML personalizzato. Qualcuno sa come si possono ridurre le dimensioni?

— aaronqli

1

Questo è di gran lunga il migliore imo, e dal momento che lo stiamo costruendo per gli sviluppatori che utilizzano desktop, la dimensione dell'output non è un problema.

— milosmns

3

L'uso del nome eseguibile diretto non sempre funziona, l'esecuzione di npx redoc-cli ...è più affidabile.

— Gattino accovacciato

21

Tutto era troppo difficile o mal documentato, quindi ho risolto il problema con un semplice script swagger-yaml-to-html.py , che funziona in questo modo

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

Questo è per YAML, ma anche modificarlo per funzionare con JSON è banale.

— oseiskar
fonte

Disponibile anche come finestra mobile ora! github.com/yousan/swagger-yaml-to-html

— noamtm

19

Dai un'occhiata a pretty-swag

Esso ha

Simile al pannello destro di Swagger-Editor
Cerca / Filtro
Schema pieghevole
Feedback in tempo reale
Uscita come un singolo file html

Stavo guardando Swagger Editor e pensavo che potesse esportare il riquadro di anteprima ma si è scoperto che non è possibile. Quindi ho scritto la mia versione di esso.

Divulgazione completa: sono l'autore dello strumento.

— TLJ
fonte

1

Ho trovato che il bel swag è uno strumento semplice e ideale, con punti di ingresso CLI e API appropriati. La mia unica e unica lamentela (e quella che mi ha costretto ad affrontare la complessità di swagger-ui invece) è stata la sua incapacità di gestire correttamente la composizione / estensione degli oggetti. Qualsiasi utilizzo di allOfnel documento produce undefined, anche negli scenari più semplici ("fusione" di un singolo oggetto, equivalente a non utilizzarlo allOfaffatto).

— HonoredMule

3

Funzionalità appena implementata allOfper te. Controlla.

— TLJ

2

Non sembra supportare Swagger / OpenAPI V3

— SeinopSys

16

Guarda il progetto swagger-api / swagger-codegen su GitHub; il progetto README mostra come utilizzarlo per generare HTML statico. Vedere Generazione della documentazione di API HTML statiche .

Se desideri visualizzare swagger.json, puoi installare l'interfaccia utente di Swagger ed eseguirlo. Devi solo distribuirlo su un server web (la cartella dist dopo aver clonato il repository da GitHub) e visualizzare l'interfaccia utente di Swagger nel tuo browser. È un'app JavaScript.

— djb
fonte

Grazie. Il mio problema era che la spavalderia-ui non accettava le specifiche 2.0. Tuttavia, questa sembra la risposta più semplice, quindi la accetterò (per ora).

— Salil

Gli strumenti Swagger si stanno ancora evolvendo per 2.0. Tuttavia, ho riscontrato che l'interfaccia utente di Swagger funziona per i miei file 2.0 che iniziano con "swagger": "2.0",

— djb

Inoltre, dall'editor Swagger, puoi esportare le specifiche JSON (non come YAML ma come JSON) e l'interfaccia utente di Swagger dovrebbe essere in grado di leggerlo. (Nota: il file swagger.json deve essere sullo stesso host / porta dell'app Swagger UI, oppure devi abilitare CORS; vedi README.md nell'editor Swagger su GitHub

— djb

14

Ho passato molto tempo e ho provato molte soluzioni diverse - alla fine l'ho fatto in questo modo:

<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>

Hai solo bisogno di avere path / to / my / swagger.yaml servito dalla stessa posizione.
(o usa le intestazioni CORS)

— Kris Randall
fonte

Fantastico, grazie! Ho utilizzato <link rel = "stylesheet" href = " petstore.swagger.io/swagger-ui.css "> <script src = " petstore.swagger.io/swagger-ui-bundle.js "></script >

— Erando

7

Puoi anche scaricare swagger ui da: https://github.com/swagger-api/swagger-ui , prendi la cartella dist, modifica index.html: cambia il costruttore

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

in

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

ora la cartella dist contiene tutto ciò di cui hai bisogno e può essere distribuita così com'è

— user1928596
fonte

2

Dai un'occhiata a questo link: http://zircote.com/swagger-php/installation.html

Scarica il file phar https://github.com/zircote/swagger-php/blob/master/swagger.phar
Installa Composer https://getcomposer.org/download/
Crea composer.json
Clone swagger-php / library
Clone swagger-ui / library
Crea classi php risorsa e modello per l'API
Esegui il file PHP per generare il json
Fornisci il percorso di json in api-doc.json
Fornisci il percorso di api-doc.json in index.php all'interno della cartella swagger-ui dist

Se hai bisogno di un altro aiuto, non esitare a chiedere.

— Syed Raza Mehdi
fonte

1

Esiste un editor online (diverso da swagger-editor) in grado di generarlo per me? Non voglio annotare le mie API PHP se esiste un modo più semplice. Il problema, ho capito, è che swagger-editor genera swagger spec v2.0, e swagger-ui non lo gestisce al momento.

— Salil

@Salil tutto quello che so è che spavalderia fornisce il proprio editor in linea cioè editor.swagger.wordnik.com Non sono a conoscenza di nessun altro editor in linea, se ne trovi condividilo con noi, grazie :)

— Syed Raza Mehdi

2

C'è un piccolo programma Java che genera documenti (adoc o md) da un file yaml.

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);

Purtroppo supporta solo OpenAPI 2.0 ma non OpenAPI 3.0 .

— Erando
fonte

2

Per Swagger API 3.0, la generazione di codice client Html2 dall'editor Swagger online funziona alla grande per me!

— Kumar S
fonte