Comment automatiser la documentation d'une API REST (implémentation Jersey) [fermé]
J'ai écrit une API REST assez étendue en utilisant Java Jersey (et JAXB). J'ai également écrit la documentation en utilisant un Wiki, mais c'était un processus totalement manuel, qui est très sujet aux erreurs, surtout lorsque nous devons apporter des modifications, les gens ont tendance à oublier de mettre à jour le wiki.
En regardant autour, la plupart des autres API REST 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é 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 requête (Get / Put / Post / Delete)
- Description
- Codes d'erreur qui peuvent être retournés
Et puis bien sûr il y a des choses générales qui sont globales telles que
- Sécurité
- Aperçu de REPOS
- Gestion des erreurs
- Etc
Ces choses générales sont bien à 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 l'automatiser.
J'ai pensé à peut-être utiliser des annotations et écrire un petit programme qui génère XML, puis un XSLT qui devrait générer la documentation réelle en HTML. Est-il plus logique d'utiliser XDoclet personnalisé?
7 answers
Swagger est une belle option. C'est un projet sur GitHub, a une intégration 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 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 étiez très prudent, les chances sont que pour une raison indépendante de votre contrôle, vous ne pouvez pas vous conformer exactement.
Même si vous le pouviez, les autres développeurs qui pourraient avoir à utiliser votre API peuvent ne pas se soucier ou connaître les détails des modèles RESTful... N'oubliez pas que le but de la création de l'API est de faciliter son utilisation par les autres et une bonne documentation est un must.
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 de la documentation de l'API.
Certaines personnes ont pris cette voie, et une feuille de style XSL a été développée pour faire la transformation: https://wadl.dev.java.net/
Bien que je ne sois pas sûr que cela corresponde totalement à vos besoins, jetez un oeil à énoncer. Il semble être un bon générateur de documentation pour diverses architectures de services Web.
EDIT Énoncer est disponible sous github parapluie
Vous pourriez être intéressé par la capacité de Jersey à fournir ce qu'on appelleWADL description pour toutes les ressources publiées au format XML à l'exécution (générées automatiquement à partir d'annotations). Cela devrait contenir déjà ce dont vous avez besoin pour la documentation de base. En outre, vous pourriez être en mesure d'ajouter JavaDoc supplémentaire, 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 exactement juste. Le type de description ne doit pas être donné aux clients d'une API REST car il conduira le développeur client à coupler l'implémentation du client à l'implémentation actuelle du service. C'est ce que la contrainte hypermédia de REST 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 le propriétés (esp. evolvability) garanti par REST.
Votre interface pourrait toujours être une meilleure solution que RPC par exemple. Mais être conscient de ce que vous construisez.
Jan
Je déteste être porteur de mauvaises nouvelles, mais si vous ressentez le besoin de documenter les choses que vous avez énumérées, alors vous n'avez probablement pas créé d'interface REST.
Les interfaces REST sont documentées en identifiant une seule URL racine, puis en décrivant le type de média de la représentation renvoyée à partir de cette URL et tous les types de média accessibles via des liens dans cette représentation.
Quels types de médias utilisez-vous?
Mettez également un lien vers RFC2616 dans vos docs. Cela devrait expliquer à tout consommateur comment interagir avec votre service.
Vous pourriez trouver reste-outil de utile. Il suit une approche agnostique 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 immédiatement être utilisée pour assurer la qualité de l'implémentation des services réels.
Si vos services ne sont pas encore complètement implémentés, mais doivent par exemple être utilisés par une application web frontend, rest-tool fournit instant moqueur basé 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.