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

Réponses:

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

  1. Similaire au panneau de droite de Swagger-Editor
  2. Recherche / Filtre
  3. Pliage de schéma
  4. Commentaires en direct
  5. 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
la 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
la 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
la 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/[email protected]/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
la 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
la source
2

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

  1. Téléchargez le fichier phar https://github.com/zircote/swagger-php/blob/master/swagger.phar
  2. Installez Composer https://getcomposer.org/download/
  3. Faire composer.json
  4. Cloner swagger-php / bibliothèque
  5. Cloner swagger-ui / bibliothèque
  6. Créer des classes PHP Resource et Model pour l'API
  7. Exécutez le fichier PHP pour générer le json
  8. Donner le chemin de json dans api-doc.json
  9. 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
la 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
la 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
la 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
la source