Projet OpenMRS

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

Rédacteur technique:

Saurabh

Nom du projet:

Extension de la documentation GitHub conviviale pour l'API REST

Durée du projet:

Durée standard (3 mois)

Project description

Objectif principal

Amélioration de la documentation sur 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 d'OpenMRS. Il existe déjà une documentation générée automatiquement basée sur Swagger pour l'API OpenMRS Webservices et une documentation statique basée sur GitHub. Nous sommes censés étendre cette documentation basée sur GitHub dans cette saison des documents.

Bref aperçu

Après quelques recherches sur OpenMRS Talk, comme l'a suggéré Burke, j'ai appris que ce projet a débuté 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 la façon dont elle était générée afin de générer une meilleure version de la documentation. Tous les détails pertinents accomplis dans le cadre du projet ont été résumés ici dans cet article de discussion OpenMRS et ont été très utiles.

Puis, en 2019, ce projet a été repensé. Nous sommes passés des ajustements de la documentation Swagger afin d'obtenir des variantes. À la place, nous avons développé une documentation statique compatible avec GitHub que nous allons étendre au cours de cette saison de Docs.

Donc, voici un résumé de la proposition de projet actuelle que j'ai l'intention de décrire :

1. Trouver des exemples dans les langages les plus courants (dont Java et JavaScript en particulier)
2. Ajout de la prise en charge de Playground pour la documentation des écrans, tout comme la fonctionnalité d'essai 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 supplémentaire dans la section Console de la documentation

DESCRIPTION DÉTAILLÉE

1. Trouver des exemples dans différentes langues.

Je vous suggère d'ajouter des exemples en Java qui seront basés sur un SDK, puis d'ajouter des exemples de remaniement qui, je pense, approfondiront notre documentation. En effet, l'ajout d'exemples dans un autre langage comme JavaScript ne sera pas aussi utile que l'ajout d'exemples de remaniement, car j'ai utilisé ces API REST lorsque j'utilisais le client Android OpenMRS, et il n'y avait pas de ressources à rechercher chaque fois que j'avais besoin d'aide pour utiliser les points de terminaison spécifiquement pour Android. Grâce à mon expérience avec les points de terminaison de l'API OpenMRS dans le client Android, je pourrais vraiment vous donner des exemples de qualité. J'en parlerai avec mes mentors et je travaillerai sur ce qui est décidé. En plus d'ajouter des exemples pour les opérations prises en charge, nous devrions également ajouter des exemples pour l'authentification avec des serveurs OpenMRS dans certains langages de programmation. À l'heure actuelle, nous ne disposons que d'exemples curl pour cela.

1. Prise en charge de Playground pour tester des exemples d'API

J'ai utilisé cette fonctionnalité dans la documentation fantaisiste d'OpenMRS hébergé sur le serveur de démonstration. C'est un outil très pratique à inclure dans n'importe quelle documentation d'API. J'ai fait quelques recherches et il n'est pas si difficile d'intégrer la spécification Swagger-UI dans la documentation statique actuelle. Utiliser des boutons d'activation/de désactivation d'affichage du masquage et utiliser le code actuel de la documentation sur le swagger dont nous disposons. Ainsi, nous pouvons même nous assurer que la fonctionnalité de test reste en ligne avec les spécifications actuelles de l'API. C'est l'une des façons dont je pense que nous pourrions intégrer les fonctionnalités de Playground dans 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'une des principales préoccupations de ce projet cette année. À l'heure actuelle, seuls des exemples curl sont disponibles dans la documentation de l'API GitHub. Il n'est pas possible d'exécuter directement ces exemples sur le serveur de démonstration pour effectuer une vérification directement depuis le navigateur. Je vais tester tous les points de terminaison actuels et conserver un document simple contenant les réponses de divers exemples curl lors de l'exécution de ces requêtes. Pour accomplir cette tâche, j'utiliserai Postman en plus de la fonctionnalité de test intégrée figurant dans la documentation commerciale.

Réponses d'API manquantes pour certains exemples

Certaines réponses ont été ajoutées pour les exemples curl suivants, mais pas certains d'entre eux. Je pense que même si les réponses ne sont pas détaillées, ce qui est généralement le cas avec des opérations comme la purge de la ressource, nous devrions avoir un exemple de réponse d'API JSON bien que nous ayons 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 sur différentes opérations

Je pense que ce sera la partie la plus importante de la refactorisation du travail accompli 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 donne une bonne référence aux développeurs expérimentés, mais laisse les nouveaux arrivants dans un état d'angoisse. Comme je l'ai appris dans cet article d'OpenMRS, les bons exemples n'ont pas de prix. Ainsi, en plus d'ajouter des exemples de travail, nous pourrions prendre en charge la mise en surbrillance de la syntaxe, qui est en fait peu efficace, car elle est fournie avec un écran, ce qui rend cela assez facile, comme je l'ai découvert ici,

Comme l'a souligné à de nombreuses reprises la simplicité et la description dans les documents au lieu d'une bonne interface utilisateur et d'une interface brillante, M. Burke respecte ces principes et essaie 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 interagissant avec la communauté, tout comme je l'ai fait dans l'article de discussion pour recueillir des descriptions pour les types d'attributs pour les ressources des formulaires qui n'étaient pas claires pour moi ici. Je travaillerais vraiment sur les choses en termes de priorité, en discutant avec mes mentors et en décidant des choses qui ajoutent vraiment de la valeur aux documents et qui doivent être accomplies en premier.

Ajouter des cas d'utilisation en tant que titre explicite

J'ai vu de nombreuses documentations sur les API juste pour les assimiler. J'ai vu que tous les cas d'utilisation étaient sous la forme d'un titre explicite. Certains cas d'utilisation ne sont pas explicitement visibles, mais sont fusionnés selon les définitions des ressources et des sous-ressources. Je pense que nous devrions nous efforcer de séparer les cas d'utilisation en tant qu'entité distincte dans la documentation afin que les développeurs ne puissent pas les rechercher.

1. Trouver et documenter les ressources manquantes

   Des ressources sont listées ici pour l'état actuel du projet, mais en consultant la dernière version de la documentation fantaisiste, j'ai pu trouver 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 obtenue avec d'autres ressources pendant la saison des documents 2019. Je discuterai des sujets à ajouter aux documents et je les ajouterai en conséquence.

CONCLUSION

Je fais partie de la communauté OpenMRS depuis un certain temps maintenant. 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 que je peux plutôt bien travailler sur ce projet d'extension de la documentation de l'API puisque je peux voir mon travail en tant que développeur moi-même et déterminer s'il facilite vraiment le travail d'autres développeurs ou non. Je me suis familiarisé avec les outils utilisés pour le référentiel 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. C'est donc une documentation OpenMR.

Je m'assurerai de communiquer les progrès chaque semaine par un message de discussion qui permettra de recueillir les commentaires de la communauté et de travailler en étroite corrélation avec mon mentor et la communauté pour tirer le meilleur parti de cette période de documentation.