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:

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 instructions 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 basée sur Swagger générée automatiquement 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 de la documentation.

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. L'objectif principal de Gayan Weerakutti é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 elle 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 accomplis dans le cadre du projet ont été résumés ici dans cette discussion OpenMRS et ont été très utiles.

Puis, en 2019, ce projet a été remanié. Nous sommes passés des ajustements de la documentation Swagger pour produire des variantes. Au lieu de cela, nous avons développé une documentation GitHub statique que nous allons développer 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 certains langages courants (en particulier Java et JavaScript).
2. Ajout de la prise en charge de Playground pour la documentation sur l'écran, tout comme la fonctionnalité d'essai Swagger.
3. Refactorisation et amélioration du travail effectué jusqu'à présent.
4. Rechercher et ajouter les ressources manquantes
5. Description un peu plus détaillée dans la section Console de la documentation

DESCRIPTION DÉTAILLÉE

1. Proposez des exemples dans différentes langues.

Je vous recommande d'ajouter des exemples en Java, qui seront basés sur un SDK, puis d'ajouter des exemples de modernisation qui, je pense, approfondiront notre documentation. En effet, ajouter des exemples dans un autre langage (JavaScript, par exemple) ne sera pas aussi utile que l'ajout d'exemples de modernisation, car j'ai utilisé ces API REST lorsque j'utilisais le client Android OpenMRS. Je n'avais aucune ressource à consulter chaque fois que j'avais besoin d'aide pour utiliser les points de terminaison spécifiquement pour Android. Étant donné mon expérience avec les points de terminaison des API OpenMRS dans le client Android, je pourrais sérieusement donner quelques exemples de qualité. J'en parlerai avec mes mentors et je travaillerai sur ce qui sera décidé. En outre, 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. Ajout de la prise en charge de Playground pour tester des exemples d'API

J'ai utilisé cette fonctionnalité dans la documentation Swagger de l'OpenMRS hébergé sur le serveur de démonstration, et c'est un outil très pratique à inclure dans n'importe quelle documentation d'API. J'ai fait quelques recherches ici 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 de l'affichage de masquage et le code actuel de la documentation Swagger dont nous disposons. De cette façon, nous pouvons même nous assurer que la fonctionnalité d'essai reste conforme aux spécifications de l'API actuelles. Je pense que c'est un moyen d'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'un des principaux points mis en avant dans ce projet cette année. À l'heure actuelle, seuls des exemples curl sont disponibles dans la documentation de l'API GitHub. Certains d'entre eux ne peuvent pas être exécutés directement sur le serveur de démonstration pour effectuer une vérification directement dans le navigateur. Je vais tester tous les points de terminaison actuels et gérer un document simple contenant divers exemples de réponses curl lors de l'exécution de ces requêtes. Si nécessaire, j'utiliserai Postman en plus de la fonctionnalité de test intégrée dans la documentation Swagger.

Réponses d'API manquantes pour certains exemples

Certaines réponses ont été ajoutées pour les exemples curl suivants, 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 avec des opérations telles que la suppression définitive de la ressource, nous devrions avoir un exemple de réponse d'API JSON. Toutefois, 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 de travail manquants sur différentes opérations

Je pense que ce sera la partie la plus importante de la refactorisation du travail précédemment 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'agacement. Comme je l'ai appris dans cet article d'OpenMRS, les bons exemples n'ont pas de prix. Par conséquent, en plus d'ajouter des exemples de travail, nous pourrions prendre en charge la mise en surbrillance de la syntaxe, qui n'est en effet pas très efficace, elle est associée à l'écran, ce qui rend cela assez facile à faire, comme je l'ai découvert ici.

Comme l'a souligné à maintes reprises M. Burke dans son message, préférant la simplicité et la description dans les documents plutôt qu'une interface utilisateur soignée et une interface brillante, j'adopte ces principes et j'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 engageant la communauté, tout comme je l'ai fait dans l'article de discussion pour recueillir des descriptions des types d'attributs pour les ressources des formulaires qui n'étaient pas claires pour moi. Je travaillerais vraiment sur les priorités du point de vue des priorités, en discutant avec mes mentors et en décidant des éléments qui ajoutent vraiment de la valeur aux documents et qui doivent être accomplis en premier.

Ajouter des cas d'utilisation en tant que titre explicite

J'ai consulté de nombreuses documentations d'API juste pour comprendre. J'ai vu que tous les cas d'utilisation figuraient sous la forme d'un titre explicite. Bien que certains cas d'utilisation ne soient pas explicitement visibles, ils sont quelque peu 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 séparer les cas d'utilisation en tant qu'entité distincte dans la documentation afin que les développeurs n'aient pas vraiment à les rechercher via les définitions.

1. Rechercher et documenter les ressources manquantes

   Les ressources de l'état actuel du projet sont listées ici, mais en consultant la dernière version de la documentation Swagger ici, j'ai trouvé de nombreuses ressources qui pourraient être ajoutées à la suite de ressources actuelle dans la documentation de l'API compatible GitHub avec la description comme cela est fait avec d'autres ressources pendant la saison des documents 2019. J'aborderai les sujets qui doivent être ajoutés 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, car je peux voir mon travail de développeur moi-même et évaluer si cela 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 i.e. SlateUI, car c'est une bonne documentation d'API.

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