Comment automatiser la documentation d'une API REST (implémentation de Jersey))
J'ai écrit une REST assez complète en utilisant Java Jersey (et JAXB). J'ai également écrit la documentation en utilisant un wiki, mais ça a été totalement manuel) processus, qui est très sujet aux erreurs, en particulier lorsque nous devons apporter des modifications, les gens ont tendance à oublier de mettre à jour le wiki.
En regardant autour, la plupart des autres REST API créent également manuellement leur documentation. Mais je me demande s'il y a peut-être une bonne solution à cela.
Le genre de choses qui doivent être documentées pour chaque point de terminaison sont:
- Nom du service
- Catégorie
- URI
- Paramètre
- Types de paramètres
- Types de réponse
- Schéma de type de réponse (XSD)
- Exemples de demandes et de réponses
- Type de demande (Get/Put/Post/Delete)
- La description
- Codes d'erreur pouvant être retournés
Et puis bien sûr, il y a des choses générales qui sont mondiales telles que
- Sécurité
- Présentation de REST
- La gestion des erreurs
- Etc
Ces choses générales sont bonnes à décrire une fois et n'ont pas besoin d'être automatisées, mais pour les méthodes de service Web elles-mêmes, il semble hautement souhaitable de les automatiser.
J'ai pensé à peut-être utiliser des annotations et écrire un petit programme qui génère du XML, puis un XSLT qui devrait générer la documentation réelle en HTML. Est-il plus judicieux d'utiliser XDoclet personnalisé?
Swagger est une belle option. C'est un projet sur GitHub, a l'intégration de Maven et de nombreuses autres options pour le garder flexible.
Guide d'intégration: https://github.com/swagger-api/swagger-core/wiki
Plus d'informations: http://swagger.io/
Malheureusement, la réponse de Darrel est techniquement correcte, mais elle est hocus-pocus dans le monde réel. Il est basé sur l'idéal sur lequel seuls certains sont d'accord et même si vous y avez fait très attention, il est probable que pour une raison hors de votre contrôle, vous ne puissiez pas vous conformer exactement.
Même si vous le pouviez, d'autres développeurs qui pourraient avoir à utiliser votre API peuvent ne pas se soucier des détails des modèles RESTful ou ne pas les connaître ... doit.
Le point d'Achim sur le WADL est cependant bon. Parce qu'il existe, nous devrions être en mesure de créer un outil de base pour générer la documentation de l'API.
Certaines personnes ont emprunté cette voie et une feuille de style XSL a été développée pour effectuer la transformation: https://wadl.dev.Java.net/
Bien que je ne sois pas sûr qu'il répondra parfaitement à vos besoins, jetez un œil à énoncer . Cela semble être un bon générateur de documentation pour diverses architectures de services Web.
[~ # ~] edit [~ # ~] Enunciate est disponible sous le parapluie github
vous pourriez être intéressé par la capacité de Jersey à fournir ce que l'on appelle [~ # ~] wadl [~ # ~] description de toutes les ressources publiées au format XML au moment de l'exécution (généré automatiquement à partir d'annotations). Cela devrait déjà contenir ce dont vous avez besoin pour la documentation de base. De plus, vous pourrez peut-être ajouter d'autres JavaDoc, bien que cela nécessite plus de configuration.
Veuillez regarder ici: https://jersey.Java.net/documentation/latest/wadl.html
La réponse de Darrel est tout à fait juste. Le type de description ne doit pas être donné aux clients d'une API REST car cela amènera le développeur client à coupler l'implémentation du client à l'implémentation actuelle du service. C'est ce que l'hypermédia de REST la contrainte vise à éviter.
Vous pouvez toujours développer une API décrite de cette façon, mais vous devez être conscient que le système résultant n'implémentera pas le style architectural REST et n'aura donc pas les propriétés (en particulier l'évolutivité) garanties par REST.
Votre interface pourrait toujours être une meilleure solution que RPC par exemple. Mais sachez ce que vous construisez.
Jan
Vous pourriez trouver rest-tool utile. Il suit une approche indépendante du langage pour écrire des spécifications, une implémentation simulée et des tests unitaires automatisés pour les API RESTful.
Vous ne pouvez l'utiliser que pour documenter vos API, mais cette spécification peut être immédiatement utilisée pour assurer la qualité de la mise en œuvre des services réels.
Si vos services ne sont pas encore entièrement implémentés, mais devraient par exemple être utilisés par une application Web frontale, rest-tool fournit une simulation instantanée basée sur la description du service. la validation du schéma de contenu (schéma JSON) peut également être facilement ajoutée à côté de la documentation et utilisée par les tests unitaires.