Certes, lors du développement de l'API, des difficultés de documentation sont apparues plus d'une fois: soit elle n'existe pas, alors elle n'affiche pas le comportement décrit dans le code.
Du point de vue du développeur, l'écriture de la documentation (interne uniquement) ne prend pas moins de temps que l'écriture du code lui-même. Est-ce familier? Alors bienvenue au chat.
Y a-t-il un problème?
Notre équipe développe l'API depuis longtemps, qui est la base de notre produit, mais à l'époque, il n'y avait pas d'utilisateurs en direct, donc personne ne voyait la nécessité de documenter quelque chose pour un usage externe. Comme toutes les équipes, nous avons commencé par la documentation interne - d'abord une méthode, puis une autre. Dans notre espace à Confluence, vous pouvez trouver une douzaine d'autres pages qui affichent de jolies informations passe-partout - quel type de méthode API, quel chemin de requête possède, quels paramètres et ce que nous obtenons dans la sortie.
Tout irait bien, mais le code est en constante évolution et en croissance, les besoins des entreprises changent. Parallèlement aux changements de code, les API peuvent changer, ce qui entraîne inévitablement des changements sur ces pages. Eh bien, si c'est une page et une seule fois. Et s'il y a plus de changements?
Nous avons trouvé une solution (notre propre vélo), autant que possible, tout en nous engageant dans les activités habituelles du développeur, sans penser à rédiger et mettre à jour la documentation interne.
Quelques solutions
Il existe différentes options pour l'interconnexion du code et de ses spécifications, mais pour moi, j'en distingue deux:
- Code d'abord, spécification ensuite
- Spécification d'abord, code suivant
Je vais commencer par le second, comme avec l'option qui nous convenait le moins.
Spécification d'abord, le code suivant concerne la génération de code, basé sur la spécification, c'est-à-dire que le code n'existe pas tant que vous n'avez pas écrit la spécification.
L'exemple le plus simple est Swagger Codegen.
Notre entreprise dispose d'équipes qui utilisent cette approche dans leur produit, mais dans notre cas, elle n'était pas très adaptée. Au moment où nous étions confrontés à un besoin, nous avions déjà écrit beaucoup de méthodes API, donc pour des raisons de documentation, nous ne voulions pas changer radicalement les processus de développement - d'abord nous écrivons des ébauches, puis nous codons et ensuite seulement la description des spécifications.
Code d'abord, spécification ensuite - tout est simple, nous écrivons d'abord le code, puis la spécification. Mais alors la question s'est posée - et si nous ne voulons pas faire de mouvements inutiles pour que la spécification soit générée?
Un certain nombre d'applications de notre entreprise utilisent cette approche, mais elle n'est pas particulièrement automatisée - les méthodes API sont pondérées avec toutes sortes d'annotations, sur la base desquelles la spécification a été générée. Mais ces mêmes annotations ne correspondent souvent pas à la réalité, car les besoins et les capacités de l'application augmentent et changent.
«Vous êtes programmeur», me suis-je dit et j'ai décidé d'écrire un petit prototype qui me permettrait de ne pas écrire toutes ces ordures de routine.
En faisant la tâche suivante et en écrivant le nième test fonctionnel, j'ai réalisé que nous avons déjà toutes les informations pour la spécification.
Nous avons des tests fonctionnels qui contiennent presque toutes les informations dont nous avons besoin:
- Comment s'appelle
- Ce qu'on appelle (paramètres, corps, en-têtes, etc.)
- Quel résultat est attendu (code d'état, corps de réponse)
Pourquoi ne pas fabriquer votre propre vélo?
Presque tout ce que nous écrivons habituellement dans les spécifications que nous avons. Le cas pour les petits - codez ce cas.
Puisque notre application est en php, la réflexion m'est venue. En utilisant un peu de magie de la réflexion, nous collectons toutes les méthodes API à notre disposition, prenons les données des tests fonctionnels, extrayons les données sur l'autorisation et son type. Des annotations habituelles aux méthodes, nous obtenons la description de la méthode elle-même. Après avoir mélangé tout cela, assaisonné avec des fonctionnalités spécifiques pour le cadre utilisé dans nos solutions, nous obtenons en quelques semaines une solution qui ne nécessite pratiquement pas de temps supplémentaire de la part du développeur.
La génération d'une spécification n'est que la première étape - vous devez obtenir la documentation de la spécification qui peut être fournie par un développeur externe. L'une des exigences de la documentation est qu'elle doit être présentée en plusieurs langues, mais pour le moment, nous ne produisons de la documentation qu'en anglais. Jusqu'à présent, assez, mais il sera nécessaire de connecter un mécanisme de réception des transferts à notre schéma de génération de spécifications.
Le problème qui était à l'origine que nous avons résolu. Mais avec cette solution, il existe de nombreux risques:
- Prix supportez votre propre vélo
- Extension des fonctionnalités nécessaires
- Mise à jour et synchronisation des traductions
Ces risques doivent être pris en compte et, s'ils commencent à fonctionner, prendre des mesures.