Conversione della specifica JSON di Swagger in documentazione HTML

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.

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

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

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.

Dai un'occhiata a pretty-swag

Esso ha

1. Simile al pannello destro di Swagger-Editor
2. Cerca / Filtro
3. Schema pieghevole
4. Feedback in tempo reale
5. 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.

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.

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)

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

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

1. Scarica il file phar https://github.com/zircote/swagger-php/blob/master/swagger.phar
2. Installa Composer https://getcomposer.org/download/
3. Crea composer.json
4. Clone swagger-php / library
5. Clone swagger-ui / library
6. Crea classi php risorsa e modello per l'API
7. Esegui il file PHP per generare il json
8. Fornisci il percorso di json in api-doc.json
9. 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.

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 .

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