Conversion de la spécification Swagger JSON en documentation HTML

88

Pour certaines API REST écrites en PHP, on m'a demandé de créer de la documentation Swagger , et comme je ne connaissais aucun moyen simple d'ajouter des annotations à ces API existantes et de créer une telle documentation, j'ai utilisé cet éditeur pour en générer pour le moment.

J'ai enregistré les fichiers JSON et YAML créés à l'aide de cet éditeur, et maintenant je dois créer la documentation Swagger interactive finale (cette déclaration peut sembler naïve et vague).

Quelqu'un peut-il me faire savoir comment je peux convertir le fichier de spécification Swagger JSON en documentation Swagger réelle?

Je suis sur la plate-forme Windows et je ne sais rien sur Ant / Maven.

yaml swagger swagger-php

— Salil
source

J'ai essayé [ github.com/wordnik/swagger-ui [ ] ( Swagger UI) mais cela ne rend pas mon json. le seul avertissement affiché est "Cette API utilise une version obsolète de Swagger! Veuillez consulter github.com/wordnik/swagger-core/wiki pour plus d'informations".

— Salil le

43

Je n'étais pas satisfait du swagger-codegenmoment où je cherchais un outil pour le faire, alors j'ai écrit le mien. Jetez un œil à bootprint-swagger

L'objectif principal par rapport à swagger-codegenest de fournir une configuration facile (même si vous aurez besoin de nodejs). Et il devrait être facile d'adapter le style et les modèles à vos propres besoins, qui est une fonctionnalité de base de la Bootprint -projet

— Nils Knappmeier
source

9

Attention: depuis le 11/2016, l'auteur de bootprint-swagger a apparemment abandonné le projet. swagger-codegen est toujours bien pris en charge.

— Brent Matzelle

22

Je suis l'auteur et le texte dit: "Je suis désolé de dire que je ne pourrai pas développer de nouvelles fonctionnalités pour ce projet dans un proche avenir. Mais: je pourrai probablement discuter et fusionner les pull-requests, et de publier de nouvelles versions. " Vous pourriez appeler cela abandonné, je l'appellerais «en attente». J'inviterai également toute personne intéressée à contribuer au projet.

— Nils Knappmeier

1

Trouvé qui spectaclegénère une documentation bien meilleure à partir de swagger JSON

— eternalthinker

Après beaucoup de lutte, j'ai trouvé cet outil très utile: api-html

— Asfandiyar Khan

57

Essayez d'utiliser redoc-cli .

J'utilisais Bootprint-OpenAPI par lequel je générait un tas de fichiers ( bundle.js, bundle.js.map, index.html, main.csset main.css.map) et vous pouvez le convertir en un seul .htmlfichier en utilisant HTML en ligne pour générer simple index.htmlfichier.

Ensuite, j'ai trouvé redoc-cli très facile à utiliser et la sortie est vraiment géniale, un seul et beau fichier index.html .

Installation :

npm install -g redoc-cli

Utilisation :

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

— Vikasdeep Singh
source

8

Cet outil fait vraiment la plus belle sortie de tous les outils mentionnés.

— Jakub Moravec

1

Celui-ci est de loin le meilleur, et comme nous le construisons pour les développeurs qui utilisent des ordinateurs de bureau, la taille de sortie n'est pas un problème.

— milosmns le

3

L'utilisation d'un nom d'exécutable direct ne fonctionne pas toujours, l'exécution par npx redoc-cli ...est plus fiable.

— Chaton accroupi

2

Très belle sortie. Merci pour la suggestion.

— Sahil Jain

1

C'est un outil génial !! Merci Vikas pour la merveilleuse suggestion bro !! Certainement bien meilleur et moins maladroit que bootstrap-openapi!

— Chaturvedi Saurabh

19

Découvrez pretty-swag

Il a

Similaire au panneau de droite de Swagger-Editor
Recherche / Filtre
Pliage de schéma
Commentaires en direct
Sortie sous forme de fichier html unique

Je regardais Swagger Editor et pensais qu'il pouvait exporter le volet de prévisualisation, mais il s'est avéré qu'il ne le pouvait pas. J'en ai donc écrit ma propre version.

Divulgation complète: je suis l'auteur de l'outil.

— TLJ
source

1

J'ai trouvé que pretty-swag était un outil simple et idéal, avec des points d'entrée CLI et API appropriés. Mon seul et unique reproche (et celui qui m'a obligé à faire face à la complexité de swagger-ui à la place) était son incapacité à gérer correctement la composition / l'extension des objets. Toute utilisation de allOfdans le document produit undefined, même dans les scénarios les plus simples ("fusionner" un seul objet, équivalent à ne pas utiliser allOfdu tout).

— HonoredMule

3

Simplement déployé la allOffonctionnalité pour vous. Vérifiez-le.

— TLJ

2

Ne semble pas prendre en charge Swagger / OpenAPI V3

— SeinopSys

18

Tout était trop difficile ou mal documenté, alors j'ai résolu cela avec un simple script swagger-yaml-to-html.py , qui fonctionne comme ça

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

C'est pour YAML, mais le modifier pour qu'il fonctionne avec JSON est également trivial.

— oseiskar
source

C'est de l'or pur!

— zemirco

16

Voir le projet swagger-api / swagger-codegen sur GitHub; le projet README montre comment l'utiliser pour générer du HTML statique. Voir Génération de la documentation de l'API HTML statique .

Si vous souhaitez afficher le swagger.json, vous pouvez installer l'interface utilisateur de Swagger et l'exécuter. Il vous suffit de le déployer sur un serveur Web (le dossier dist après avoir cloné le dépôt à partir de GitHub) et d'afficher l'interface utilisateur de Swagger dans votre navigateur. C'est une application JavaScript.

— djb
source

Merci. Mon problème était que swagger-ui n'acceptait pas les spécifications 2.0. Cependant, cela ressemble à la réponse la plus simple, donc je l'accepterai (pour l'instant).

— Salil le

Les outils Swagger évoluent toujours vers 2.0. Cependant, j'ai trouvé que Swagger UI fonctionne pour mes fichiers 2.0 qui commencent par "swagger": "2.0",

— djb

De plus, à partir de l'éditeur Swagger, vous pouvez exporter la spécification JSON (pas en tant que YAML mais en tant que JSON) et l'interface utilisateur de Swagger devrait être capable de lire cela. (Remarque: le swagger.json doit être sur le même hôte / port que l'application Swagger UI, ou vous devez activer CORS; voir le README.md dans Swagger Editor sur GitHub

— djb

14

J'ai passé beaucoup de temps et essayé beaucoup de solutions différentes - à la fin je l'ai fait de cette façon:

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

Vous avez juste besoin d'avoir le chemin / vers / mon / swagger.yaml servi à partir du même endroit.
(ou utilisez les en-têtes CORS)

— Kris Randall
source

Génial merci! J'ai utilisé <link rel = "stylesheet" href = " petstore.swagger.io/swagger-ui.css "> <script src = " petstore.swagger.io/swagger-ui-bundle.js "></script >

— Erando le

1

J'ai trouvé que c'était la meilleure solution, sans aucune installation!

— KurioZ7

Extrêmement utile. Vous avez gagné beaucoup de temps.

— kalpesh khule le

7

Vous pouvez également télécharger swagger ui depuis: https://github.com/swagger-api/swagger-ui , prenez le dossier dist, modifiez index.html: changez le constructeur

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

dans

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

maintenant le dossier dist contient tout ce dont vous avez besoin et peut être distribué tel quel

— user1928596
source

2

Jetez un œil à ce lien: http://zircote.com/swagger-php/installation.html

Téléchargez le fichier phar https://github.com/zircote/swagger-php/blob/master/swagger.phar
Installez Composer https://getcomposer.org/download/
Faire composer.json
Cloner swagger-php / bibliothèque
Cloner swagger-ui / bibliothèque
Créer des classes PHP Resource et Model pour l'API
Exécutez le fichier PHP pour générer le json
Donner le chemin de json dans api-doc.json
Donner le chemin de api-doc.json dans index.php dans le dossier swagger-ui dist

Si vous avez besoin d'une autre aide, n'hésitez pas à demander.

— Syed Raza Mehdi
source

1

Existe-t-il un éditeur en ligne (autre que swagger-editor) qui peut générer cela pour moi? Je ne souhaite pas annoter mes API PHP s'il existe un moyen plus simple. Le problème, j'ai compris, c'est que swagger-editor génère la spécification swagger v2.0, et swagger-ui ne gère pas cela pour le moment.

— Salil le

@Salil tout ce que je sais, c'est que swagger fournit son propre éditeur en ligne, c'est-à-dire editor.swagger.wordnik.com Je ne connais aucun autre éditeur en ligne, si vous en trouvez, partagez-le avec nous, merci :)

— Syed Raza Mehdi

2

Il existe un petit programme Java qui génère des documents (adoc ou md) à partir d'un fichier 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);

Malheureusement, il ne prend en charge qu'OpenAPI 2.0 mais pas OpenAPI 3.0 .

— Erando
source

2

Pour Swagger API 3.0, générer du code client Html2 à partir de Swagger Editor en ligne fonctionne très bien pour moi!

— Kumar S
source

1

J'ai trouvé cet outil appelé api-html très utile. Cela génère une interface utilisateur html5 impressionnante avec beaucoup de possibilités.

Il existe des options pour générer en ligne ou via l' outil cli .

Voici un lien vers la version démo sur "api-html": pets-demo

— Asfandiyar Khan
source