Howto automatiser la documentation de l'API REST (Maillot de mise en Œuvre)

Question

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.

En regardant 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
• Les Types De Réponses
• 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

• 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?

Toute aide serait grandement appréciée, Alan

Answer 1

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/wordnik/swagger-core/wiki

Plus d'Informations: http://swagger.wordnik.com/

Answer 2

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/

Answer 3

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.

Answer 4

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.

Il est toujours possible de 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