Projet OpenMRS

Cette page contient les détails d'un projet de rédaction technique accepté pour la Google Season of Docs.

Résumé du projet

Organisation Open Source:
OpenMRS
Rédacteur technique:
Saurabh
Nom du projet:
Étendre la documentation GitHub conviviale pour l'API REST
Durée du projet:
Durée standard (3 mois)

Project description

Objectif principal

Améliorer la documentation de l'API REST OpenMRS basée sur Swagger pour ajouter des conseils sur l'utilisation de l'API.

Description du projet

L'API REST OpenMRS est l'un des principaux mécanismes permettant aux développeurs d'accéder aux données OpenMRS. Il existe déjà une documentation générée automatiquement basée sur Swagger pour l'API OpenMRS Webservices, ainsi qu'une documentation statique basée sur GitHub. Nous devrions étendre cette documentation basée sur GitHub au cours de cette saison de documentation.

BREF APERÇU

Après quelques recherches sur OpenMRS Talk, comme l'a suggéré Burke, j'ai découvert que ce projet avait commencé en 2017 en tant que projet GSOC. Avec Gayan Weerakutti, l'objectif principal était d'améliorer la documentation existante de l'API REST OpenMRS, en améliorant sa spécification Swagger et en améliorant la façon dont sa spécification Swagger est générée afin de générer une meilleure version de la documentation Swagger elle-même. Tous les détails pertinents du projet ont été résumés dans cet article de discussion OpenMRS et ont été très utiles.

En 2019, ce projet a été remanié, et nous avons abandonné les modifications de la documentation Swagger qui produisaient des variantes. Nous avons donc développé une documentation statique compatible avec GitHub que nous allons développer dans cette saison de documentations.

Voici un bref résumé de la proposition de projet actuelle que je vais décrire :

  1. Proposer des exemples dans certains langages populaires (Java et JavaScript sont spécifiquement mentionnés).
  2. Ajout de la prise en charge du bac à sable pour la documentation Slate, comme la fonctionnalité de "test" de Swagger.
  3. Refactorisation et amélioration du travail effectué jusqu'à présent.
  4. Rechercher et ajouter les ressources manquantes
  5. Ajout d'une description plus détaillée à la section de la console de la documentation

DESCRIPTION DÉTAILLÉE

  1. Proposez des exemples dans différentes langues.

Je suggère d'ajouter des exemples en Java qui seront basés sur le SDK, puis d'ajouter des exemples de retrofit, ce qui, selon moi, ajoutera de la profondeur à notre documentation. En effet, ajouter des exemples dans un autre langage comme JavaScript ne sera pas aussi utile que d'ajouter des exemples de retrofit. J'ai utilisé ces API REST lorsque je travaillais sur le client Android OpenMRS, et il n'y avait aucune ressource à consulter lorsque j'avais besoin d'aide pour utiliser les points de terminaison spécifiquement pour Android. Je pourrais faire des exemples de qualité, compte tenu de mon expérience de manipulation des points de terminaison de l'API OpenMRS dans le client Android. Je vais en discuter avec mes mentors et travailler sur la décision qui sera prise. Outre l'ajout d'exemples pour les opérations prises en charge, nous devons également ajouter des exemples pour l'authentification avec des serveurs OpenMRS dans certains langages de programmation. Pour le moment, nous ne disposons que d'exemples curl pour cela.

  1. Ajout de la prise en charge de Playground pour tester des exemples d'API

J'ai utilisé cette fonctionnalité dans la documentation Swagger d'OpenMRS hébergée sur le serveur de démonstration. C'est un outil très pratique à avoir dans toute documentation d'API. J'ai fait quelques recherches et il n'est pas si difficile d'intégrer la spécification Swagger-UI à la documentation statique actuelle. Utiliser les boutons d'activation/de désactivation de l'affichage et/ou le cache, et utiliser le code actuel de la documentation Swagger. De cette façon, nous pouvons même nous assurer que la fonctionnalité d'essai reste active avec les spécifications d'API actuelles. C'est l'un des moyens, selon moi, d'intégrer les fonctionnalités de l'espace de jeu à notre documentation statique actuelle.

  1. Refactorisation et amélioration du travail effectué jusqu'à présent
Vérifier les exemples curl actuels

Cette section est l'un des principaux axes de ce projet cette année. À l'heure actuelle, seuls des exemples curl sont disponibles dans la documentation de l'API GitHub, dont certains ne peuvent pas être exécutés directement sur le serveur de démonstration pour les vérifier directement depuis le navigateur. Je vais tester tous les points de terminaison actuels et gérer un document simple contenant les réponses de divers exemples curl que nous obtenons lors de l'exécution de ces requêtes curl. Si nécessaire, j'utiliserai Postman en plus de la fonctionnalité d'essai intégrée dans la documentation Swagger.

Réponses de l'API manquantes pour certains exemples

Certaines réponses ont été ajoutées aux exemples curl actuels, mais certains d'entre eux n'en comportent pas. Je pense que même si les réponses ne sont pas détaillées, ce qui est généralement le cas pour des opérations telles que la purge de la ressource, nous devrions avoir un exemple de réponse d'API JSON. Nous avons documenté tous les codes de réponse possibles et la raison de les obtenir. Je pense que cela rendrait les exemples de la documentation de l'API plus uniformes.

Exemples fonctionnels manquants pour différentes opérations

Je pense que ce sera la partie la plus importante du refactoring du travail précédemment effectué dans la documentation de l'API. La documentation contient des exemples concrets qui peuvent être exécutés directement avec cURL, mais certains d'entre eux sont un peu abstraits, ce qui constitue une bonne référence pour les développeurs expérimentés, mais laisse les nouveaux venus dans un état de gêne. D'après ce post sur la discussion OpenMRS, les bons exemples sont inestimables. En plus d'ajouter des exemples de travail, nous pourrions prendre en charge la mise en surbrillance de la syntaxe, ce qui ne demande pas beaucoup d'efforts, car il est fourni avec Slate, ce qui le rend très facile à faire,

Comme Burke l'a souligné à plusieurs reprises dans son post, en privilégiant la simplicité et la description dans les documents plutôt qu'une interface utilisateur attrayante, je vais respecter ces principes et essayer de rendre les points de terminaison précédemment documentés aussi descriptifs que possible en discutant avec les développeurs qui travaillent actuellement sur l'API OpenMRS Webservices et en impliquant la communauté, comme je l'ai fait dans le post de discussion pour recueillir des descriptions des types d'attributs des ressources de formulaires qui n'étaient pas claires dans ma PR ici. Je travaillerais vraiment en fonction des priorités, en discutant avec mes mentors et en déterminant les éléments qui ajoutent vraiment de la valeur aux documents et qui doivent être réalisés en premier.

Ajouter des cas d'utilisation en tant que titre explicite

J'ai consulté de nombreuses documentations d'API pour m'en familiariser et j'ai constaté que toutes présentaient les cas d'utilisation en tant que titre explicite. Bien que nous ayons des cas d'utilisation, ils ne sont pas explicitement visibles. Ils sont en quelque sorte fusionnés dans les définitions et les exemples qui suivent les définitions des ressources et des sous-ressources. Je pense que nous devrions faire l'effort de séparer les cas d'utilisation en tant qu'entité distincte dans la documentation afin que les développeurs n'aient pas vraiment à rechercher dans les définitions les cas d'utilisation, mais qu'ils puissent simplement les rechercher.

  1. Trouver et documenter les ressources manquantes

    Les ressources sont listées ici dans l'état actuel du projet, mais en consultant la dernière version de la documentation Swagger ici, j'ai pu identifier de nombreuses ressources qui pourraient être ajoutées à la suite actuelle de ressources dans la documentation de l'API compatible avec GitHub, avec la description réalisée pour d'autres ressources lors de la saison de la documentation 2019. Je vais discuter des sujets qui doivent être ajoutés aux documents et les ajouter de manière appropriée.

CONCLUSION

Je fais partie de la communauté OpenMRS depuis un certain temps. Je contribue activement au projet client Android, dans lequel j'interagis souvent avec les API pour interagir avec les serveurs. Par conséquent, je pense pouvoir travailler sur ce projet d'extension de la documentation de l'API assez bien,car je peux voir mon travail en tant que développeur et évaluer s'il facilite vraiment le travail des autres développeurs ou non. Je me suis familiarisé avec les outils utilisés pour le dépôt de documentation convivial hébergé ici. J'ai également apporté plusieurs contributions à ce dépôt afin de me familiariser avec le dépôt et les outils, par exemple slateUI. Étant donné qu'une API est considérée comme aussi bonne que sa documentation, j'aimerais améliorer les API REST OpenMRS en améliorant sa documentation.

Je m'assurerai de communiquer les progrès hebdomadairement via un post de discussion, ce qui me permettra de recueillir les commentaires de la communauté. Je travaillerai en étroite collaboration avec mon mentor et la communauté pour tirer le meilleur parti de cette période de documentation.