Slate vs Swagger - Quel est le meilleur et lequel a le plus d'options?
Swagger et Slate ont deux objectifs différents. Swagger est une tentative d'une manière standardisée de décrire une API RESTful (similaire, par exemple, à ApiBlueprint )
Swagger est un format de définition d'API basé sur JSON, qui permet la description des API REST.
~ Outils de conception d'API de Swagger
Slate, d'autre part, est un joli thème pour écrire des documents Nice API.
- Les deux ne s'excluent pas mutuellement
- Idéalement, il faut générer votre documentation détaillée à partir de la description de votre API Swagger
Le but de Swagger est de fournir une norme sur laquelle d'autres peuvent construire des outils étendus (par exemple: documentation, explorateurs d'API, serveurs fictifs, génération de code, utilitaires de test, etc.). Voir, par exemple: Swagger Tooling
Plus à votre question: Certains outils Slate pour swagger:
- Voici un lien vers une interface utilisateur sur le thème Slate
- Voici un projet qui génère des documents Slate basés sur votre définition Swagger
Donc, les deux ne s'excluent pas mutuellement, mais à votre question directe: l'implémentation de Swagger vous donnera plus d'options et une plus grande flexibilité (ainsi que la possibilité de générer également une documentation Slate).
De mon point de vue, ces outils ont des objectifs très différents. Swagger est un langage de description, tandis que l'ardoise est juste pour la documentation.
J'ai utilisé swagger pour créer une descriptionn, à partir de laquelle je peux générer automatiquement différents clients pour mon API, même générer automatiquement de la documentation.
Vous pouvez également créer Markdown à partir de la spécification swagger et utiliser ces démarques dans Slate. [1]
À propos de l'ardoise:
- Modèle/Framework de documentation API
- Cela semble bon
- facilité d'utilisation
- Mise en évidence de la syntaxe
- Spécifique à la langue - à onglets
- Recherche de page
- Disposition personnalisable à 3 colonnes
- Nous pouvons créer une table
- Liens défilants vers chacun des blocs/méthodes/en-têtes
- Fonction d'alerte [3 types] - avertissement, succès, avis
- Tableaux des codes d'erreur http
- Syntaxe de démarque
- Nous pouvons utiliser le logo du site
- Démo
À propos de Swagger:
- Il nous donne un accès API à l'intérieur des documents lui-même, où nous pouvons vérifier la réponse pour toute demande particulière.
- Il donne une image claire des réponses de l'API avec leurs paramètres et options. - Format basé sur YAML
- Ne convient pas pour l'API hypermédia
- Il n'y a pas d'outils de conception pour Swagger
- Les réponses sont en XML ou JSON
- Swagger JS - Bibliothèque JavaScript pour se connecter aux API activées par swagger via un navigateur ou nodejs
- Swagger Node Express - Module Swagger pour module express node.js
- Il a un cadre d'interface utilisateur fanfaron
- Démo
Je fais un flacon en ardoise ( https://github.com/AhnSeongHyun/slate-flask ) basé sur un flacon en python.
fonctionnalités:
Fichier de configuration (config.json): Définissez le titre, le langage de programmation, par exemple les codes utilisant la base config.json au format JSON. Définissez également le chemin des documents API et de la table des matières.
Prise en charge des documents multi-API: Original Slate prend en charge un document API basé sur le format Markdown. Mais l'ardoise prend en charge les documents multi-API pour une gestion efficace et la quantité de documents à l'aide de la table des matières (index.json).
Prise en charge des modifications dynamiques des documents: vous pouvez refléter les modifications des documents API sans redémarrer le serveur. Lors de l'actualisation de la page Web, s'il existe des modifications, ardoise-flacon recharger les documents API. Les utilisateurs se concentrent uniquement sur l'écriture de documents API.