De nombreuses questions ont été publiées et ont répondu à propos des API basées sur le repos / HTTP, etc., mais aucune ne semble avoir beaucoup d'informations sur la question suivante:
Quels outils sont disponibles / utilisés pour documenter une API HTTP-RPC? Quels outils sont les meilleurs?
Une question similaire (spécifique à asp.net) à partir de janv. 2009 peut être trouvée ici , mais sans réponses.
Je suis en train de développer plusieurs API à la fois professionnels et pour des projets personnels (.NET MVC / OpenRASta, PHP, Coldfusion, etc.), et je n'ai rien trouvé en particulier pour aider à documenter ces API. Je ne cherche pas une génération automatique basée sur un analysant / nettoyage de code ou quelque chose comme ça. Comme vous connaissez probablement déjà déjà une API basé sur HTTP / HTTP, doit être client et plate-forme agnostique; En tant que tel, je m'attendrais à ce que tout outil de documentation soit identique.
Caractéristiques qu'un outil décent pourrait avoir:
Voici quelques exemples de ce que j'envisage de la documentation / référence (s) d'API décente ressemble à:
http://dev.twitter.com/doc/post/ Status / Détruire /: ID
http://www.salesforce.com/us/developer /docs/api_REST/index.htm
4 Réponses :
L'une des raisons pour lesquelles un tel outil n'existe pas est que la documentation d'une API reposante ne devrait pas inclure aucun de ces éléments:
La documentation de l'API reposant concerne la documentation des types de supports utilisés et de leur sémantique d'application associée. Vous devriez chercher à produire quelque chose qui ressemble plus à Ceci .
Les exemples que vous avez donnés sont des API de RPC basées sur HTTP, c'est pourquoi ils nécessitent ce type de documentation de l'extrémité. Ils sont reposants en nom seulement. Maintenant, pourquoi les gens ne créent pas d'outils pour documenter automatiquement les API RPC basées sur HTTP, je ne peux pas vraiment vous dire. C'est peut-être parce que les personnes qui écrivent ces API sont si occupées à les maintenir qu'ils n'ont pas le temps de rédiger des outils de documentation!
Je comprends que vous ne comprenez pas, et je ne cherche pas à argumenter la sémantique, pour EXMAPLE en.wikipedia.org/wiki / Repossible est assez trompeur sur le sujet. Personnellement, je distinguerais une application reposante et une API reposante comme deux entités différentes. Cependant, dans l'intérêt de la santé mentale, je mettrai à jour ma question pour être plus précis!
-1: Pothots dogmatiques sur la praticité. Les API de repos ont également besoin de la documentation. Quels codes d'état HTTP est-ce que je m'attendais à recevoir à des fins de validation? Comment l'authentification est-elle traitée? Quel jeu de caractère suis-je censé utiliser? À quoi ressemble la charge utile? Est-ce que des parties sont facultatives? Quel type de données les composants individuels acceptent-ils? Vous notez que ces choses, comme la sémantique des applications, valent la peine de documenter, mais vous semblez nier qu'un outil pouvant être utilisé pour documenter facilement cela devrait exister, le prenant plutôt que l'existence d'un outil signifie que vous avez choisi le mauvaise solution.
Code d'état @jesper à des fins de validation: 400. L'authentification est traitée mais l'en-tête de l'authentification www. Soit le type de média ou la relation de liaison vous indiquera à quoi ressemble la charge utile. Charset? Type de média Documents. Composants facultatifs, Type de média Documents. Si un outil peut le documenter par magie, il est possible de vous retrouver avec DOCS qui disent «Get / Client pour récupérer un client». Quel IMHO est 100% redondant. Dans un système reposant, la découverte des ressources devrait être dynamique et non dans la documentation.
@DarrelMiller: Vous devez parler d'une autre sorte d'API de repos. API de Twitter documente tout ce . Je suis totalement d'accord que la pseudo-documentation comme celle-ci est complètement inutile. Ce n'était pas la question originale cependant; C'est "Comment apposer apposer une documentation justifiée à ma liste d'appels" qui dans un contexte de repos constituerait une liste des ressources et des opérations autorisées. Le repos n'est pas limité à haïrons, où vos points sont beaucoup plus applicables.
@Jesper "repos n'est pas limité à haïrons" apparemment, le gars qui a inventé le terme n'est pas d'accord: roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driv en
@DarrelMiller: Je sais ce que dit la thèse de Roy Fielding (et ce que dit Roying en général). Je sais aussi quelle est la majorité des API de repos (auto-étiquetées) utilisées. Je ne dis pas que je ne regarde pas avec impatience son avenir, mais ce n'est pas encore ici et, entre-temps, nous devons tous traiter avec les systèmes de nos environs qui existent.
Après de nombreuses recherches que j'ai découvertes, ce n'est pas un outil qui fait exactement ce que je veux. Il existe un certain nombre d'outils qui sont très nombreux dans la bonne direction, mais sont souvent spécifiques à la langue et ne génèrent pas de documentation de référence HTTP API / RPC, mais plutôt de la documentation de référence de Code / Bibliothèque / API.
En conséquence, je prévois de créer l'outil que j'ai besoin / envisage à partir de zéro. Si / quand j'ai quelque chose à montrer, je mettrai à jour ma réponse.
Des mises à jour sur cette création d'outils?
J'ai créé des spécifications pour l'outil et un schéma de données, mais je n'ai pas encore besoin de la construire tristement.
Swagger mérite probablement un oeil pour vous avoir besoin. Je l'utilise pour documenter les entrées de repos exposées par une application Java à l'aide de Jersey, mais on dirait que vous pouvez également l'utiliser avec d'autres langues.
C'est à peu près ce que je cherchais. Merci :)
Vous devez jeter un coup d'œil à l'application Swagger, comme cela déjà mentionné par @ ZIM2001. Il possède un composant Swagger-UI, qui est une application HTML simple et JavaScript, lecture des données JSON enregistrées par l'application Backend. Il existe des adaptateurs pour le nombre de langues, y compris PHP et Java.
Si vous utilisez le cadre Symfony2 pour PHP, voici un ensemble prêt à l'emploi pour la génération automatique de la documentation de service réparatoire:
Une chose que je n'aime pas à propos de ces générateurs est le manque de traductions, donc si vous souhaitez fournir la documentation de votre API exposée sur des services reposants sur de nombreuses langues - vous ne pouvez pas.
Lunatech-Labs.com/open-source/jax-doclets looks prometteur mais je ne l'ai pas utilisé moi-même. En outre, il est spécifique à Java, bien que peut-être les idées derrière elle seront portées dans d'autres langues ...
Ce serait génial si j'utilisais Java: P Cependant, cela serait certainement utile pour les futurs projets Java, donc merci pour le lien!
J'ai créé un simple modèle pour les documentations de l'API reposant: Github.com/berb/res-Doc-Template < / a> Peut-être que c'est utile pour vous aussi. Sinon, vous voudrez peut-être faire une fourchette et cela l'utiliser comme fondation.
Un autre excellent exemple de documentation API reposante: twilio.com/docs/api/res/call < / a>
Un article sur certaines options: APIEVANGELIST .COM / 2014/01/16 / ...