Proyecto OpenMRS

Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la GDOC Season of Docs.

Resumen del proyecto

Organización de código abierto:

OpenMRS

Redactor técnico:

Saurabh

Nombre del proyecto:

Extensión de la documentación de GitHub fácil de usar para la API de REST

Duración del proyecto:

Duración estándar (3 meses)

Project description

Objetivo principal

Mejora la documentación de la API de REST basada en Swagger de OpenMRS para agregar orientación sobre el uso de la API.

Descripción del proyecto

La API de REST de OpenMRS es uno de los mecanismos clave para que los desarrolladores accedan a los datos de OpenMRS. Ya existe una documentación generada automáticamente basada en Swagger de la API de OpenMRS Webservices y una documentación estática basada en GitHub. Se supone que extenderemos esa documentación basada en GitHub en esta temporada de documentos.

DESCRIPCIÓN GENERAL BREVE

Después de investigar un poco sobre OpenMRS Talk, como sugirió Burke, me enteré de que este proyecto comenzó en 2017 como un proyecto de GSOC. Con Gayan Weerakutti, donde el objetivo principal era mejorar la documentación existente de la API REST de OpenMRS, mejorando su especificación de Swagger y a través de mejoras en la forma en que se genera su especificación de Swagger para que se genere una mejor versión de la documentación de Swagger. Todos los detalles relevantes logrados en el proyecto se resumieron aquí en esta publicación de la charla de OpenMRS y fueron muy útiles.

Luego, en 2019, se renovó este proyecto y pasamos de los ajustes de documentación de Swagger que producían variaciones sobre este. En su lugar, desarrollamos una documentación estática que es compatible con GitHub que vamos a extender en esta temporada de Documentos.

Entonces, un resumen de la propuesta de proyecto actual que tengo la intención de describir es el siguiente :

1. Crear ejemplos en algunos lenguajes populares (específicamente, Java y JavaScript)
2. Se agregó compatibilidad con el campo de pruebas para la documentación de Slate, al igual que la función de "prueba" de Swagger.
3. Refactorización y mejora del trabajo realizado hasta ahora.
4. Buscar y agregar los recursos que faltan
5. Se agregó un poco más de descripción a la sección de la consola de la documentación.

DESCRIPCIÓN DETALLADA

1. Crea ejemplos en diferentes idiomas.

Te sugiero agregar ejemplos en Java, que estarán basados en el SDK, y luego agregar ejemplos de reajuste, que creo que darán más profundidad a nuestra documentación, ya que agregar ejemplos en un lenguaje más, como JavaScript, no será tan útil como agregar ejemplos de remodelación, ya que he usado estas APIs de REST mientras trabajaba en el cliente OpenMRS Android y no había recursos para consultar cada vez que necesitaba ayuda para usar los extremos específicamente para Android. Y podría hacer algunos ejemplos de calidad aquí, dada mi experiencia con los extremos de la API de OpenMRS en el cliente de Android. Hablaré sobre esto con mis mentores y trabajaré en lo que se decida. Además, además de agregar ejemplos para las operaciones admitidas, también deberíamos agregar ejemplos para autenticarse con servidores de OpenMRS en algunos lenguajes de programación. Por el momento, solo tenemos ejemplos de curl para esto.

1. Se agregó compatibilidad con Playground para probar ejemplos de APIs

Usé esta función en la documentación de Swagger del OpenMRS alojada en el servidor de demostración y es una herramienta muy conveniente para tener en cualquier documentación de API. Investigué un poco aquí y no es tan difícil incorporar la especificación Swagger-UI en la documentación estática actual. Usar los botones de activación para ocultar y mostrar, y el código de documentación de Swagger actual que tenemos De esta manera, incluso podemos asegurarnos de que la función de prueba siga activa con las especificaciones actuales de la API. Creo que esta es una forma en la que podríamos integrar las funciones de Playground en nuestra documentación estática actual.

1. Refactorización y mejora del trabajo realizado hasta ahora

Cómo verificar los ejemplos actuales de curl

Esta sección es uno de los aspectos principales de este proyecto de este año. En la actualidad, solo hay ejemplos de curl en los documentos de la API de GitHub, algunos de los cuales no se pueden ejecutar directamente en el servidor de demostración para verificarlos directamente desde el navegador. Probaré todos los extremos actuales y mantendré un documento simple con varias respuestas de ejemplos de curl que obtengamos cuando ejecutemos esas solicitudes. Usaré Postman junto con la función integrada de prueba en la documentación de Swagger para realizar esta tarea si es necesario.

Faltan respuestas de la API en algunos ejemplos

Se agregaron algunas respuestas para los ejemplos actuales de curl, pero algunos de ellos no tienen respuestas. Creo que incluso si las respuestas no son detalladas, lo que suele suceder con operaciones como la eliminación definitiva del recurso, deberíamos tener un ejemplo de respuesta de la API de JSON aunque hemos documentado todos los códigos de respuesta posibles y el motivo para obtenerlos. Creo que esto haría que los ejemplos en toda la documentación de la API sean más uniformes.

Faltan ejemplos de funcionamiento en varias operaciones.

Creo que esta será la parte más importante de refactorizar el trabajo realizado anteriormente en la documentación de la API. Hay ejemplos concretos en la documentación que se pueden ejecutar directamente con cURL, pero algunos de ellos son un poco abstractos, lo que proporciona una buena referencia a los desarrolladores experimentados, pero deja a los principiantes en un estado de molestia. Como pude entender en esta publicación de la charla de OpenMRS, los buenos ejemplos no tienen precio, así que, aparte de agregar ejemplos de trabajo, podríamos admitir el resaltado de la sintaxis, que en realidad no es mucho trabajo, viene en paquete con cortinilla de video, lo que hace que esto sea bastante fácil de hacer como descubrí aquí.

Como Burke enfatizó muchas veces en su publicación que prefiere la simplicidad y la descriptividad en los documentos en lugar de una buena IU y una interfaz atractiva, me ceñiría a estos principios y trataría de hacer que los extremos documentados anteriormente sean lo más descriptivos posible hablando con los desarrolladores que actualmente trabajan en la API de OpenMRS Webservices y que interactúan con la comunidad, tal como lo hice en la publicación de la charla para recopilar descripciones de los tipos de atributos de los recursos de formularios que no me quedaron claros en mi PR aquí. Trabajaría en las prioridades, hablaría con mis mentores y decidiría cuáles son los aspectos que realmente agregan valor a los documentos y que deben realizarse primero.

Agrega casos de uso como un título explícito

Vi mucha documentación de la API solo para acostumbrarme a ella y vi que todas tenían casos de uso como un título explícito. Aunque tenemos casos de uso que no son visibles de forma explícita, están un poco fusionados dentro de las definiciones y los ejemplos que siguen después de las definiciones de los recursos y subrecursos. Creo que deberíamos esforzarnos por separar los casos de uso como una entidad independiente en la documentación para que los desarrolladores no tengan que buscar en las definiciones que infieren los casos de uso, sino que puedan buscarlos.

1. Buscar y documentar los recursos faltantes

   El estado actual del proyecto tiene recursos que se enumeran aquí, pero al ver la versión más reciente de la documentación de Swagger aquí, pude descubrir muchos recursos que podrían agregarse al conjunto actual de recursos en los documentos de la API compatibles con GitHub con la descripción que se realizó con otros recursos durante la temporada de Documentos 2019. Analizaré los temas que se deben agregar a los documentos y los agregaré de forma adecuada.

CONCLUSIÓN

Hace tiempo que formo parte de la comunidad de OpenMRS. Soy un colaborador activo del proyecto de cliente de Android, en el que interactúo con las APIs con frecuencia para interactuar con los servidores. Por lo tanto, creo que puedo trabajar en este proyecto de extender la documentación de la API bastante bien, ya que puedo ver mi trabajo como desarrollador y evaluar si realmente facilita el trabajo de otros desarrolladores. Me familiaricé con las herramientas que se usan para el repositorio de documentación fácil de usar alojado aquí. También hice varias contribuciones a este repositorio para familiarizarme con el repositorio y las herramientas, es decir, slateUI. Como se cree que una API es tan buena como su documentación, me encantaría mejorar las APIs de OpenMRS Rest mejorando su documentación.

Me aseguraré de comunicar el progreso semanalmente con una publicación de charla que ayudará a obtener los comentarios de la comunidad y trabajar en estrecha correlación con mi mentor y la comunidad para aprovechar al máximo este período de documentación.