Cette page contient les détails d'un projet de rédaction technique accepté pour Google Season of Docs.
Résumé du projet
- Organisation Open Source:
- OpenMRS.org
- Rédacteur technique:
- batbrain7
- Nom du projet:
- Documentation de l'API REST OpenMRS
- Durée du projet:
- Durée standard (3 mois)
Project description
Je vais décomposer ma proposition en plusieurs sections et suivre le flux, comme la documentation de l'API Google Maps et celle de l'API GitHub.
En plus de ces éléments, je souhaite également vous proposer une structure de fichier Lisez-moi pour la documentation de l'API réalisée par realworld.io : https://github.com/gothinkster/realworld/tree/master/api
Personnellement, j'ai trouvé cette documentation très facile à comprendre et à utiliser.
Ma proposition comporterait principalement trois sections :
Une section qui donne une brève présentation de l'API, d'OpenMRS, de son utilisation et de ce qui suit.
Comment obtenir la clé API et l'authentification nécessaire en général pour envoyer la requête API Vous y trouverez un exemple des types d'authentification présents dans l'API, des clés et des valeurs qui doivent être présentes, ainsi que des types de valeurs acceptées correspondant à la clé dans cette partie. Un exemple de code dans n'importe quel langage permettrait de clarifier comment écrire les en-têtes, les formats de réponse et les autres paramètres de requête dans l'API.
Les types de réponses récupérées par l'API, les types de JSON ou tout autre type de résultat renvoyés par les API doivent être mentionnés.
Les différentes routes d'API, ce que tous les paramètres doivent être envoyés, ainsi que ceux-ci, les en-têtes et d'autres éléments. Chaque API sera accompagnée d'exemples de code dans quelques langages qui décrivent la façon dont la requête est effectuée lors de la rédaction du code associé, à l'exception des codes d'erreur généraux pouvant survenir avec chaque API.
Il s'agit d'une idée générale de la manière dont la documentation sera définie pour l'API REST.
Le calendrier du projet est le suivant :
1er août - 1er septembre
Faire la connaissance de mon mentor et discuter plus en détail du niveau de documentation requis dans les différentes parties du codebase et de l'importance d'aller dans la documentation de bas niveau et de haut niveau. Je vais également consacrer ce temps à comprendre le codebase et à étudier les concepts afin de mieux les documenter.
Semaines 1 et 2
Je vais mettre à jour et développer le guide des contributeurs. J'améliorerai la documentation sur la façon de créer le code source. J'ajouterai également une section documentaires sur la façon dont les nouveaux contributeurs peuvent aider dans la documentation. Je vais étudier la documentation des différentes API, puis commencer par l'introduction et ajouter l'authentification pour l'API.
Semaines 3 - 8
Je vais ajouter les routes et les réponses des API, ainsi que des exemples de code pour chaque type d'API (il peut exister des types d'API similaires).
Semaines 9 et 10
Ajouter la structuration de la documentation de l'API à l'aide de liens, c'est-à-dire un index lié pour une documentation longue de l'API, et la diviser davantage sur une base différente (sections de code, présentation, paramètres, points de terminaison racine, etc.)
Dernière semaine
Je vais utiliser la dernière semaine pour préparer mon rapport final sur le travail effectué au cours de ma période de documentation de 12 semaines. Je vais également prendre le temps d'examiner et de finaliser la documentation.