Générateur de Documentation API rESTful JSON

Question

Je me demandais si quelqu'un a de l'expérience ou des recommandations d'outils qui peuvent être utilisés pour générer des pages web de ce document et vous permettent de jouer avec un RESTful API JSON. Je suis en train de penser à quelque chose comme le Github Développeur de l'API ou de l'API Google Console.

En regardant autour, j'ai trouvé swagger de Wordnik, ce qui semble bon. Mais je me demandais si il n'y a rien d'autre là-bas et ce que l'expérience des gens est avec ces outils. Je vous remercie.

Answer 1

Il y a quelque chose d’autre comme énoncer et Docs d’e/s.

Et voici un blog sur ce sujet : Documentation automatisée pour REST API

Answer 2

J’aime le rucher. Toujours dans le flux, mais l’air assez bon.

Answer 3

la question est assez vieux, mais je crois est toujours d'actualité. Je suis conscient des trois API outils de conception:

• Swagger (il n'y a pas de solution SaaS)
• RAML (apihub.com)
• API Plan (apiary.com) Tous d'entre eux sont couverts dans ce blog - http://apievangelist.com/2014/03/08/hello-world-product-api-with-blueprint-raml-and-swagger/
  Je recommande fortement de suivre ce gars, si vous êtes intéressé par Api

Personnellement, je pense que ces outils sont bons pour le partage de docs de l'API entre les membres de relativement petites équipes de développeurs où chaque développeur est conscient de la plupart des détails spécifiques pour un projet particulier, et ils ont littéralement juste besoin de savoir si c'est POST ou PUT et qu'est-ce que les noms de résultat JSON champs.

Nous avons riches et pratique des fonctionnalités de gestion de contenu le long avec le RESTE spécifiques des trucs qui permettrait de produire de beaux documents dans divers formats comme une seule page html ou pdf Nous ne pouvions pas trouver de logiciel décent, de sorte que nous avons décidé de créer Speca.io

Pour le moment il est en alpha et totalement gratuite, mais nous sont très bienvenus pour jouer et que tous les commentaires seront appréciés.

Answer 4

Swagger pourrait être pour vous. Il a des implémentations dans différentes langues.

Answer 5

Ma recommandation serait de ne pas faire confiance à la [ document à partir du code source ] générateurs de trop. Je pense que le public de document est enfin l'homme et ils ont besoin de beaucoup plus que ce que le WADL de machine et les fichiers générés peuvent fournir. Pour aider les outils que vous avez à investir du temps et des efforts pour maîtriser la idosyncracies d'un outil.

Aussi, il existe une réelle limite pratique sur la façon dont beaucoup peuvent être inclus dans le code source de l'API. Simplement de documenter les noms de paramètres et les types ne sera pas une partie de l'aide (et complète) et l'ajout de l'échantillon de demande et de réponse à l'intérieur du code source ressemble simplement mauvais (même si des informations essentielles pour les utilisateurs finaux). Une autre raison peut être simplement de l'esthétique.

Twitter maintient également les documents à la main et qui dit beaucoup de choses. À mon humble avis, la meilleure option serait de conserver la documentation de l'Humain, de format plus convivial et générer du HTML /PDF etc.

Shameless Plug

https://github.com/rjha/restdoc

C'est juste quelques très simples scripts PHP de lire API de YAML fichiers de définition et de générer le code HTML. Ne peut pas à l'échelle pour EBay type d'API énorme, mais pour la simple documentation de l'API exigences ce peut être un moyen d'aller.