Comment faire pour automatiser la documentation de l'API REST (Maillot de mise en Œuvre)

J'ai écrit un assez vaste, API REST en Java Jersey (et JAXB). J'ai également écrit la documentation à l'aide d'un Wiki, mais sa fait un totalement processus manuel, ce qui est très enclin à l'erreur, surtout quand nous avons besoin de faire des modifications, les gens ont tendance à oublier de mettre à jour le wiki.

De regarder autour, la plupart des autres RESTE de l'API sont également manuellement la création de leur documentation. Mais je me demandais si il y a peut-être une bonne solution pour cela.

Le genre de choses qui doivent être documentées pour chaque point de terminaison sont:

  • Service De Nom
  • Catégorie
  • URI
  • Paramètre
  • Les Types De Paramètre
  • Types De Réponse
  • De réponse Type de Schéma (XSD)
  • Les demandes d'échantillons, et les réponses
  • Le type de la requête (Get/Put/Post/Delete)
  • Description
  • Les codes d'erreur qui peuvent être retournés

Et puis bien sûr, il ya quelques choses générales qui sont de portée mondiale, tels que

  • De sécurité
  • Aperçu de REPOS
  • Erreur de manipulation
  • Etc

Ces choses sont très bien pour décrire une fois et n'ont pas besoin d'être automatisé, mais pour les méthodes de service web eux-mêmes, il semble hautement souhaitable de l'automatiser.

J'ai pensé peut-être à l'aide d'annotations, et à écrire un petit programme qui génère le XML, puis une transformation XSLT qui devrait générer la documentation disponible au format HTML. Est-il plus logique d'utiliser des XDoclet?

  • Enunciate.codehaus.org tire la documentation à partir de la documentation Javadoc: il est open source et fonctionne avec Jersey, de sorte que vous pourriez peut-être regarder à cela?
  • double possible de API RESTful de Documentation
  • J'ai été en utilisant énoncer quelques années maintenant et il a quelques bizarreries. Il ne gère pas les types personnalisés si bien et devient tout à fait confus avec résumé otd. Enfait, je suis sur ce post droit maintenant à la recherche pour son remplacement
InformationsquelleAutor Alan Mc Kernan | 2009-11-11
  1. 41

    Swagger est une belle option. C'est un projet sur GitHub, a Maven, intégration et des tas d'autres options pour rester souple.

    Guide d'intégration: https://github.com/swagger-api/swagger-core/wiki

    Plus D'Informations: http://swagger.io/

    Comment faire pour automatiser la documentation de l'API REST (Maillot de mise en Œuvre)

    InformationsquelleAutor Webnet
  2. 21

    Malheureusement, Darrel la réponse est techniquement correct, mais est-hocus-pocus dans le monde réel. Il est basé sur l'idéal que seulement quelques-uns d'accord et même si vous avez été très prudent à ce sujet, les chances sont que pour une raison indépendante de votre volonté, vous ne pouvez pas se conformer exactement.

    Même si vous le pouvez, d'autres développeurs que pourrait avoir l'utilisation de votre API peut pas de soins ou de connaître les détails des modèles Reposant... n'oubliez pas que le point de la création de l'API est de le rendre facile pour les autres de l'utiliser et d'une bonne documentation est un must.

    Achim point sur la WADL est bon cependant. Parce qu'il existe, nous devrions être en mesure de créer un outil de base pour la génération de la documentation de l'API.

    Certaines personnes ont pris cette voie, et une feuille de style XSL a été développé pour effectuer la transformation:
    https://wadl.dev.java.net/

    • Pourriez-vous m'indiquer les documents qui ont montré que les développeurs de navigateurs web comment accéder à l'information sur stackoverflow.com? Ou sont ces gars-là ne fait pas partie du monde réel?
    • Pas besoin de choisir un combat Darrel. Je n'ai aucune idée de ce que le débordement de la pile de gens ont mis en place en termes d'une API et je n'aime pas beaucoup parce que je n'ai pas besoin de ça. Si ils n'ont pas à fournir de la documentation à leur API alors je suis désolé pour la personne qui doit intégrer.
    • Il n'y avait aucune agressivité prévu. Je suis aussi de ne pas se référant à la Stackoverflow API. Je fais référence à ce site web. Le site web fonctionne sur HTTP et est consommé par une application client appelle un "navigateur web". Mon point est que lorsque vous générez un site web, vous n'avez pas besoin de faire appel à Google pour leur dire comment s'adapter Chrome de sorte qu'il peut consommer votre site web. En utilisant bien documenté types de médias, il n'est pas nécessaire pour "API" document.
    • Chrome est contrôlé par un opérateur humain. La plupart des API clients sont automatiques. Si vous voulais naviguer Stackoverflow.com avec un robot que vous auriez besoin intime connaissance de la structure et de l'utilisation prévue du site. Vous ne serait pas "l'explorer à partir d'une URL de la racine du" ni espérer que les médias de type "text/html" fournir beaucoup d'aide. Vous auriez fin de l'exploration à la main pour créer le genre de la carte une bonne documentation de l'API fournit.
    • Le stackoverflow API a beaucoup de documentation (voir la section api.stackexchange.com/docs ) cette notion de ne pas documenter une API ReSTful est ridicule dans le monde réel et ne peut en aucune façon aider à répondre à la question d'origine.
    InformationsquelleAutor Brill Pappin
  3. 16

    Bien que je ne suis pas sûr que ça va totalement s'adapter à vos besoins, prendre un coup d'oeil à énoncer. Il semble comme un bon générateur de documentation pour divers services web architectures.

    MODIFIER Énoncer est disponible sous github parapluie

    • Meilleure réponse. Aussi, Énoncer a maven soutien (intégration facile).
    • Il y a aussi style
    • J'ai regardé énoncer, puis est allé à Swagger.
    • Elle demande de nom d'utilisateur et Mot de passe
    • Ouais, codehaus a été fermé, donc énoncer doit avoir déplacé ...
    • j'ai adoré codehaus il a été une partie de ma vie et me donne la larme à l'oeil en voyant qu'il ouvre pas plus! fin d'une époque

    InformationsquelleAutor Riduidel
  4. 8

    vous pourriez être intéressé en Jersey à la capacité de fournir dite WADL description de toutes les ressources publiées au format XML au moment de l'exécution (générés automatiquement à partir des annotations). Cela devrait être contenant déjà ce dont vous avez besoin pour la documentation de base. En outre, vous pourriez être en mesure d'ajouter d'autres JavaDoc, mais qui nécessite plus de configuration.

    Veuillez regarder ici:
    https://jersey.java.net/documentation/latest/wadl.html

    InformationsquelleAutor
  5. 3

    Darrel la réponse est tout à fait exact. Le type de description ne doit pas être donnés à des clients d'une API REST, car il aidera le développeur client à couple de la mise en œuvre de la client à la mise en œuvre actuelle du service. C'est ce qui RESTE de l'hypermédia contrainte vise à éviter.

    Vous pouvez toujours développer une API qui est décrit de cette façon, mais vous devez être conscient que le système qui en résulte ne sera pas mettre en place le RESTE de style architectural et ne seront donc pas les propriétés (esp. l'évolutivité) garanti par le REPOS.

    Votre interface peut encore être une meilleure solution que la RPC par exemple. Mais être conscient de ce que vous construisez.

    Jan

    • Pourrait les électeurs laisser un commentaire? Donc, on sait ce qui se passe?
    InformationsquelleAutor Jan Algermissen
  6. 0

    Vous pourriez trouver reste-outil utile.
    Il résulte de la langue agnostique approche de l'écriture de la spécification, de se moquer de la mise en œuvre et automatisée de tests unitaires pour RESTful Api.

    Vous pouvez l'utiliser seulement pour la documentation de votre Api, mais cette spécification peut être immédiatement utilisé pour assurer la qualité de la mise en œuvre des services réels.

    Si vos services ne sont pas pleinement mis en œuvre, mais par exemple doit être utilisé par une interface web de l'application, reste-outil fournit instantanément des moqueries basé sur la description du service. contenu de la validation du schéma JSON (schéma) peut également être facilement ajouté à côté de la ainsi que de la documentation utilisée par les tests unitaires.

    InformationsquelleAutor tombenke
  7. -1

    Je déteste être le porteur de mauvaises nouvelles, mais si vous sentez le besoin de documenter les choses que vous avez énumérés, alors vous n'avez probablement pas créer une interface REST.

    RESTE interfaces sont documentées par l'identification d'une seule racine de l'URL et puis en décrivant le type de média de la représentation, qui est retourné à partir de l'URL et tous les types de supports qui peuvent être accessibles via des liens dans cette représentation.

    Quels types de supports utilisez-vous?

    Aussi, mettre un lien vers RFC2616 dans vos documents. Qu'il faut expliquer à tous les consommateurs à interagir avec votre service.

    • Eh bien, vous auriez probablement souhaitez quand même fournir une documentation pour les différents itinéraires que vous avez, de droite?
    • Dépend de ce que tu veux dire par des voies. Du point de vue du client, il a besoin de comprendre à partir de la description du type de média quels sont les liens qu'il peut suivre. Si c'est ce que vous entendez par les routes, alors oui. Cependant, si les itinéraires de vous dire ce que l'Url du serveur expose alors non, ne devraient pas être inclus dans la documentation pour le client.
    • Si vous vous allez downvote vous devriez vraiment avoir le courage de le justifier.
    • Si vous êtes en se référant à la Découverte de suffisamment de documentation pour une interface REST, votre soit de mauvais à l'écrit, de l'API ou vous écrivez très petit et facile à digérer services. Je dirais que c'est dur de s'auto générer de la documentation de l'API que vous devez penser en termes d'OBJECTIFS de l'UTILISATEUR et là, dans le flux de travail. Surtout nous devons penser en termes de "Quoi de mon API ne, Ce qui peut ma Ressource à faire", et non pas en termes de "Ce que les utilisateurs veulent faire?"... RESTE exploite un peu de tout cela en vous permettant de dire "Ce que vous pouvez faire à partir d'ici", mais qui peut ne pas être suffisant.
    • quand j'écris des clients, je ne fais pas d'hypothèses sur les ressources qui existent sur le serveur. De la même manière d'un navigateur web ne fait aucune hypothèse sur les pages web existent.
    • Documenter les flux de travail et l'utilisateur final des objectifs n'a pas à être explicite sur l'endroit où les ressources sont situés. C'est à propos de dire à l'utilisateur "Comment il/elle fait un achat" parce que c'est son/le sien intention, un but. Au lieu de dire à lui/elle "Comment vous ajoutez un article à votre panier (qui se trouve être un document de quelque sorte)" dans l'isolement, vous pouvez dans ces documents ont pour le rendre évident pour l'utilisateur qu'il/elle se sera dit au cours de la procédure où aller..
    • Type de support de documentation, ou d'une application au niveau sémantique profil de amundsen.com/hypermedia/profiles devrait être utilisé pour décrire les flux de travail de l'utilisateur.
    • Juste pour être clair, lorsque vous mentionnez le type de Média que ce serait ce que nous avons utilisé pour désigner le type MIME? Si si je suis en désaccord. Nous n'avons pas tendance à faire ces choses parce que nous ne pensons pas que les développeurs comme nous pensons que les utilisateurs généraux, mais nous devrions le faire. Une application au niveau sémantique profil peut être conceptuellement ce que je recherche, j'ai pu voir ils ont parlé de l'avancement de l'état d'une ressource, alors oui, mais vous n'avez jamais soutenu qu'avant. Mais l'exemple est un affreux alors. Le problème est que nous pensons souvent que notre interfaces est évident et manifeste à d'autres développeurs instantanément, elles ne le sont jamais.
    • Que c'est stupide. Une API REST est juste que, une API. Il n'y a pas moyen d'écrire un client générique qui sait comment interagir avec chaque API REST, peu importe comment l'auto-documentation qu'ils sont. Un client aura une bonne connaissance de l'API de boulangerie et de production de la documentation pour décrire l'API semble sain d'esprit.
    • Pouvez-vous m'indiquer les documents que les navigateurs web, les développeurs ont utilisé lors de la construction de support pour la StackOverflow site web? Et avant de vous revenir avec "mais les navigateurs web sont différents". Demandez-vous, pourquoi sont-ils différents. Ils sont originaires des applications qui consomment le HTML/CSS/jpeg/png types de média à partir d'un serveur HTTP qui expose des ressources.
    • Chrome travaux en raison de normes et il rend. Il n'a pas d'interagir avec un service de moins que de le faire, et même alors, l'utilisateur doit donner des instructions précises et l'URI pour Chrome pour effectuer l'interaction. C'est pas de la magie. La plupart de REPOS clients ont la coutume de l'interaction et de la clientèle de rendu des systèmes basés sur la structure des données de réponse. Je n'ai aucune idée de comment vous en sortir sans documentation, sauf si vous êtes le seul consommateur. Au lieu de parler des navigateurs et internet, me montrer monde réel RESTE des services qui ont zéro de la documentation qui sont faciles à écrire des clients pour.
    • Sérieusement? Vous pouvez ainsi créer une énigme de service puis de dire au consommateur de RTFM?!
    • Je ne suis pas sûr de l'endroit où je l'ai suggéré que les gens devraient créer cryptique services. Concernant la lecture de la spécification HTTP, oui, je pense que tout le monde à l'aide de HTTP devraient lire la spec.
    • Je DÉTESTE ce genre de réponses. La Documentation n'est pas seulement pour les développeurs. Je ne peut pas part de mon vendeur le RFC spec sur HTTP et de demander à leurs perspectives de comprendre eux-mêmes. Ah, vous avez été faire du logiciel pour plus de 20 ans - il tous les sens maintenant...
    • Est-ce à la documentation du sens pour vous? amundsen.com/hypermedia/profiles
    • parle HATEOAS: l'idée qu'un Réparateur document devrait contenir des liens énumération de tous les possibles "prochaines étapes" ou "articles connexes'. Cela fait sens pour le HTML parce que nous voulons que nos navigateurs pour afficher des liens sur une page afin que nous puissions naviguer en cliquant simplement, plutôt que de continuellement en tapant la nouvelle Url dans le champ URL. Pour une API RESTful si ce n'est pas comme beaucoup de sens: un système automatisé client a besoin de savoir quelque chose au sujet de ce service, il parle à tout, et il n'est pas déraisonnable de demander au client de composer les Url dont il a besoin.
    • Vous avez raison, il n'est pas déraisonnable de demander au client de composer des URL. Cependant, ce ne serait pas une bonne système, repos, les systèmes doivent être hypertexte conduit. Reposant clients ne DOIVENT pas prendre des dépendances sur le serveur de la structure des ressources.
    • Selon Roy Fielding (roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven) vous avez raison, Reposant systèmes doivent être hypertexte à moteur. Cependant, je pense que c'est une position extrême, et qu'il est important et productif de la classe de l'Api qui embrasse HTTP et de souligner les noms, les types de médias, l'apatridie, le contrôle des versions de documents, etc., mais faire disparaître HATEOAS et autoriser les clients à construire leurs propres URLs... et que c'est ce que la plupart des gens familièrement qualifier de "REPOS" de nos jours. Ce serait formidable si nous avons eu un nouveau terme.
    • Un certain nombre d'entre nous tout simplement se référer à ceux de l'Api HTTP. Il est malheureusement qu'il n'y a pas plus visible publiquement hypermédia conduit Api. Je ne pense pas que cela prendrait trop de temps à voir qu'ils ne sont pas près de "extrême", car elles sont perçues et sont vraiment très efficaces dans la pratique des scénarios.
    • C'est improductif, pipe de rêve réponse, plus approprié pour la discussion philosophique de Débordement de la Pile. Cette discussion serait intéressant, vous l'esprit, mais ici c'est juste de faire du prosélytisme.
    • Cette réponse est à tarte-dans-le-ciel non-sens qui utilise un pédant définition d'un service REST et est totalement hors de contact avec la réalité en ce qui concerne la façon dont le REPOS est utilisé dans le monde réel.
    • Juste par curiosité, avez-vous déjà essayé d'utiliser une API documentée de cette façon? J'ai aussi travaillé avec l'OpenAPI façon de décrire les Api, donc j'ai travaillé avec les deux approches.
    • J'ai honnêtement jamais vu un service qui utilise le HATEOAS principe dans la nature, je suppose que c'est parce que très peu de cas d'utilisation se prête à ce principe. Assurez-vous que la plupart des gens appellent RESTE de ces jours est un hybride de la RPC et de REPOS, mais c'est parce que c'est ce qui a évolué basé sur l'utilisation du monde réel et non pas pur le milieu universitaire. OPs question est basée sur cette approche hybride.
    • Vous n'avez jamais vu hypermédia utilisé "dans la nature", vous pensez "très peu de cas d'utilisation", "tarte-dans-le-ciel non-sens", "hors de contact avec la réalité", "pur milieu universitaire". Toutes les déclarations tapé dans une application native, entraînée par un hypermédia type de support et la prise de HTTP API basée sur les appels à une distance l'adresse HTTP du serveur d'origine. Ces arbres sont d'une forêt.

    InformationsquelleAutor Darrel Miller