openapi gui

OpenAPI-GUI

OpenAPI-GUI est une interface graphique pour créer et modifier les définitions OpenAPI Version 3.0.x JSON / YAML. Dans sa forme actuelle, il est le plus utile comme outil pour démarrer et modifier les définitions OpenAPI simples. Les définitions OpenAPI 2.0 importées sont automatiquement converties en V3.0.

Pour la version précédente Swagger / OpenAPI 2.0 uniquement, voir ici. Cette version est actuellement non entretenue en dehors des correctifs de sécurité.

Ce projet était initialement une fourche de l'iodoctor de Daryl Kuhn, qui à son tour a été inspiré par l'iodoctor par Brandon West qui a été écrit en Ruby. L'historique complet du projet est maintenu sur GitHub.

Description

Comment ça marche

Sélectionnez une définition OpenAPI 2.0 ou 3.0.x existante pour télécharger ou créer une nouvelle définition et commencer à ajouter des chemins, des opérations et des paramètres. Lorsqu'une définition existante est utilisée, elle est analysée et des formulaires pour modifier chaque chemin, le fonctionnement et le paramètre seront créés.

Vous pouvez charger une définition existante en ajoutant un paramètre ?url= requête sur la page de démarrage initiale, la valeur étant l'URL à la définition que vous souhaitez charger. Lorsque vous utilisez Docker, vous pouvez définir la valeur du paramètre de requête url sur %2fserve pour récupérer la définition que vous avez transmise sur la ligne de commande Docker.

Cliquez sur un élément dans le menu à gauche pour commencer l'édition. Affichez la sortie JSON / YAML à tout moment en sélectionnant l'un des onglets "Exporter". Une fois terminé, téléchargez la sortie pour l'enregistrer localement ou copiez votre presse-papiers. OpenAPI-GUI stocke une seule définition à la fois, et c'est dans le stockage local de votre navigateur. Assurez-vous d'enregistrer localement votre sortie JSON / YAML.

Avant d'effectuer une action destructrice, OpenAPI-Gui enregistre l'état actuel de la définition. À tous les autres moments, vous devez vous rappeler de sélectionner Enregistrer manuellement.

Technologie

OpenAPI-Gui s'exécute entièrement côté client en utilisant un certain nombre de frameworks JavaScript, notamment Vue.js, JQuery et Bulma pour CSS.

Pour que l'application soit opérationnelle, parcourez simplement la version en direct sur les pages GitHub, déployez un clone sur les pages GitHub, déployez sur Heroku en utilisant le bouton ci-dessous, ou clonez le référentiel et pointez un navigateur sur index.html ou l'hébergez vous-même - ne pourrait pas être plus simple. Plus d'informations techniques ici.

Vous avez besoin d' npm install les modules Node.js que si vous souhaitez utiliser le serveur Web embarqué openapi-gui (c'est-à-dire pas si vous exécutez votre propre serveur Web), sinon ils ne sont là que pour les déploiements PAAS.

Options de CLI

 -d, --definition    serve the given OAS definition
-l, --launch        start a web-browser pointing to the GUI
-p, --port          specify the port to run on, defaults to $PORT or 3000
-w, --write         enable writing back to the source definition

Courir avec Docker

Si vous n'avez pas d'environnement de développement de nœuds local, ou si vous préférez exécuter OpenAPI-GUI dans un conteneur Docker, vous pouvez faire avec quelques étapes simples:

1. Clone le référentiel.
2. Exécutez docker build -t mermade/openapi-gui . Pour construire l'image Docker ( mermade/openapi-gui )
3. Exécutez docker run --name openapi-gui -p 8080:3000 -d mermade/openapi-gui Pour exécuter le serveur sur le port 8080.
4. Accédez à http://localhost:8080 dans votre navigateur préféré.
5. Lorsque vous avez terminé, arrêtez le serveur en exécutant docker stop openapi-gui && docker rm openapi-gui

Ou vous pouvez tirer l'image docker prédéfinie:

• docker pull mermade/openapi-gui

Limites

• OpenAPI-GUI déserrera les paramètres partagés.
• La définition doit être autonome sans $ref externe. Cela est probablement résolu bientôt (ho-ho) .
• Le montage d'un schéma de réponse / exemple / corps le déférera.
• OpenAPI-GUI ne préservera pas toujours les extensions des fournisseurs, par exemple si un paramètre est supprimé et recréé.
• OpenAPI-GUI ne préservera pas les commentaires des définitions importées au format YAML.

FAIRE

• Voir la liste TODO et l'état actuel de la prise en charge des spécifications OpenAPI 3.0.