web-dev-qa-db-fra.com

Conversion de la documentation JSON des spécifications Swagger en documentation HTML

Pour certaines REST API écrites en PHP, il m'a été demandé de créer Swagger documentation, 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 je dois maintenant créer la documentation interactive finale de Swagger (cette déclaration peut sembler naïve et vague).

Quelqu'un peut-il me dire, s'il vous plaît, comment je peux convertir le fichier de spécification Swagger JSON en une documentation Swagger réelle? 

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

yamlswaggerswagger-php
55
Salil

swagger-codegen ne me satisfaisait pas lorsque je cherchais un outil pour le faire, alors j'ai écrit le mien. Regardez bootprint-swagger

L'objectif principal par rapport à swagger-codegen est de fournir une configuration simple (bien que vous ayez besoin de nodejs) . Et il devrait être facile d'adapter le style et les modèles à vos propres besoins, ce qui est une fonctionnalité essentielle de bootprint -projet

30
Nils Knappmeier

Découvrez pretty-Swag

Il a

  1. Aspect similaire à Swagger-Editor panneau de droite
  2. Rechercher/Filtrer
  3. Schéma Pliant
  4. Commentaires en direct
  5. Sortie sous forme de fichier HTML unique

J'étais en train de regarder Swagger Editor et je pensais qu'il pouvait exporter le volet de visualisation, mais il s'est avéré que ce n'était pas le cas. Alors j'en ai écrit ma propre version.

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

16
TLJ

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 documentation api html statique .

Si vous souhaitez afficher swagger.json, vous pouvez installer l'interface utilisateur Swagger et l'exécuter. Vous venez de le déployer sur un serveur Web (le dossier dist après avoir cloné le référentiel depuis GitHub) et d'afficher l'interface utilisateur Swagger dans votre navigateur. C'est une application JavaScript.

13
djb

Essayez d'utiliser redoc-cli.

J'utilisais bootprint-openapi pour générer un groupe de fichiers (bundle.js, bundle.js.map, index.html, main.css et main.css.map), puis vous pouvez le convertir en un seul fichier .html à l'aide de html-inline to générer un simple fichier index.html. 

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

Installation:

npm install -g redoc-cli

Usage:

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

Tout était trop difficile ou mal documenté, j'ai donc résolu ce problème avec un script simple swagger-yaml-to-html.py , qui fonctionne comme ceci

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.

7
oseiskar

Vous pouvez également télécharger swagger ui depuis: https://github.com/swagger-api/swagger-ui , Prendre le dossier dist, modifier index.html: Changer 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

6
user1928596

J'ai passé beaucoup de temps et essayé différentes solutions - à la fin, je l'ai fait comme suit:

<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 devez simplement avoir path/to/my/swagger.yaml servi au même endroit.
(ou utilisez les en-têtes CORS)

5
Kris Randall

Consultez 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. Installer Composer https://getcomposer.org/download/
  3. Faire composer.json
  4. Clone swagger-php/bibliothèque
  5. Clone 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. Donne le chemin de json dans api-doc.json
  9. Donne 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.

2
Syed Raza Mehdi

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 supporte que OpenAPI 2.0 mais pas OpenAPI 3.0 .

0
Erando