Quelle est la meilleure façon de générer une documentation de l'API REST?

Je cherche un moyen sympa de générer de la documentation pour une API REST. Il n'a pas besoin de se connecter avec le code ou quoi que ce soit d'autre, mais ce serait génial de pouvoir écrire la documentation sous forme de fichiers texte, de pointer l'outil dessus et d'en générer des docs.Quelle est la meilleure façon de générer une documentation de l'API REST?

Quelqu'un a-t-il des idées? Je sais que je suis un peu vague, mais, pour être honnête, je ne suis pas sûr de ce que je cherche ici - principalement un moyen facile de gérer la documentation.

Source

2010-10-14 Kyle Slattery

Pourquoi? Je veux dire, vraiment, pourquoi ne pas simplement écrire de la documentation dans Open Office ou quelque chose et l'enregistrer en PDF, XML, etc? D'autres outils, comme doxygen, sont destinés à générer de la documentation à partir du code source et des commentaires qui s'y trouvent. –

Désolé, aurait dû mentionner - Je veux générer des fichiers HTML à partir de celui-ci, mais je préfère ne pas être en train de modifier le code HTML pour le générer. Je suis vraiment à la recherche d'un moyen de sauvegarder les docs dans un format avec un formatage minimal (en utilisant Markdown ou quelque chose de similaire) et ensuite transformer cela en un tas de fichiers HTML liés. –

According to Roy:

"A REST API should spend almost all of its descriptive 
effort in defining the media type(s) used for representing 
resources and driving application state, or in defining 
extended relation names and/or hypertext-enabled mark-up 
for existing standard media types."

Self-est l'un des descriptif avantages de repos.

Source

2010-10-14 21:49:09 fumanchu

Je pense que le point clé est qu'il n'y a vraiment pas de manière standardisée de documenter un type de média. Si seulement il y avait. Cela ne peut certainement pas être généré. –

Bien que n'étant pas REST, j'ai utilisé Sphinx pour documenter une API XML-RPC qui consistait en une référence API et un tutoriel. Sphinx ajoute quelques directives pratiques à ReStructuredText pour obtenir à peu près ce que vous avez demandé: une collection de fichiers au format texte ReStructuredText que Sphinx transforme en HTML et PDF, avec un index et une table des matières. Sphinx est facile à utiliser et bien documenté; Je ne pense pas qu'il serait exagéré de dire que vous pourriez commencer avec cela dans une dizaine de minutes.

Source

2010-10-15 16:28:11 ddbeck

Certains systèmes RESTful sont en mesure d'écrire leur propre API. Jetez un oeil à RESTx, qui fait exactement cela: Vous écrivez vos composants et ensuite créez de nouveaux services Web en envoyant des paramètres pour ces composants au serveur (soit sous forme de JSON ou via un formulaire Web). Vous obtenez alors une adresse URI pour ces paramètres. L'accéder appelle le composant avec les paramètres et vous récupérez les résultats. En tout état de cause, les composants ainsi que les services Web RESTful créés reçoivent une documentation générée automatiquement, consultable et pouvant être récupérée au format HTML ou JSON. Pourquoi avez-vous besoin d'un fichier texte avec documentation pour générer de la documentation?

Source

2010-10-15 16:29:47 jbrendel

Quelle est la meilleure façon de générer une documentation de l'API REST?

Répondre

Questions connexes