web-dev-qa-db-fra.com

Générer des documents statiques avec swagger

Existe-t-il une méthode permettant de créer une documentation statique pour swagger 2.0? Peut-être comme l’aperçu sur editor.swagger.io.

Je dois obtenir des fichiers HTML statiques pour pouvoir les inclure dans certains documents statiques.

Jusqu'à présent, je n'ai pas trouvé le moyen de le faire. Je vois qu'il existe swagger-codegens static-docs , Mais cela ne fonctionne que pour swagger <= 1.2.

swagger
42
romeovs

Utilisez swagger-codegen:

swagger-codegen generate -i <path to your swagger file> -l html2 -o <path to output location>

Si vous décidez de personnaliser le modèle HTML:

  1. Clonez le projet swagger-codegen de github
  2. Copiez le dossier modules/swagger-codegen/src/main/resources/htmlDocs2 dans un autre emplacement, par exemple: cp -R modules/swagger-codegen/src/main/resources/htmlDocs2 ~/templates
  3. Modifiez les modèles .mustache dans ~/templates pour répondre à vos besoins.
  4. Exécuter: swagger-codegen generate -i <path to your swagger file> -l html2 -o <path to output location> -t <templates path> pour <templates path> devrait être ~/templates dans l'exemple ci-dessus.
19
BananaWanted

Si vous souhaitez simplement générer des documents statiques de manière simple, considérez Spectacle .

npm install spectacle-docs si vous voulez mettre un script dans votre package.json, ou npm install -g spectacle-docs s'il devrait être disponible partout.

Ensuite, vous pouvez simplement exécuter spectacle spec.yaml, avec des options pour créer un répertoire spécifique, exécuter un serveur et/ou regarder le fichier de spécifications et le mettre à jour si nécessaire.

13
Will

La static-docs en 2.0 est implémentée pour 2.0. voir le ./bin/static-docs.sh ici:

https://github.com/swagger-api/swagger-codegen/tree/master/bin

5
fehguy

Si vous recherchez spécifiquement Swagger 2.0, je voudrais vous indiquer ma réponse dans Conversion du JSON de la spécification Swagger en documentation HTML , Bien que je crois que Swagger-Codegen prend désormais en charge Swagger 2.0 .

2
Nils Knappmeier

Vous pouvez utiliser:

1
slal

Les documents "statiques" peuvent signifier plusieurs choses.

Si vous recherchez un affichage interactif (comme l'aperçu de l'éditeur), vous avez swagger-ui ( https://github.com/swagger-api/swagger-ui ).

Le code dans le codegen qui utilise les documents les plus statiques (sans le bouton "Essayez-le maintenant", par exemple) n'est pas encore implémenté pour 2.0 mais devrait être disponible dans les prochaines semaines. 

1
Ron

Cliquez sur les documents de prévisualisation, utilisez l'extension chrome "Enregistrer la page WE" (clic droit sur la page -> "Enregistrer la page"), le résultat est un fichier html unique (il ne peut pas être cliqué, vous devez donc cliquer sur tout ce que vous voulez voir).

0
Jiro Matchonson

J'ai utilisé la procédure décrite ici http://ics.upjs.sk/~novotnyr/blog/2156/create-html-documentation-from-swagger-via-maven .

Il utilise Maven pour générer une documentation statique et le résultat est assez lisible. Il semble être hautement configurable et extensible, bien que je ne l’aie pas encore essayé.

0
paul