Proyecto OpenMRS

Esta página contiene los detalles de un proyecto de redacción técnico aceptado para Google 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

Mejoramos la documentación de la API de REST basada en OpenMRS Swagger para agregar orientación en 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 hay una documentación generada automáticamente basada en Swagger de la API de OpenMRS Webservices y también una documentación estática basada en GitHub; se supone que debemos extender esa documentación basada en GitHub en esta temporada de Documentos.

DESCRIPCIÓN GENERAL DEL BREVE

Después de investigar un poco sobre OpenMRS Talk como sugirió Burke, supe que este proyecto comenzó en 2017 como un proyecto del GSOC. Con Gayan Weerakutti, el objetivo principal era mejorar la documentación existente de la API REST de OpenMRS, al mejorar su especificación de Swagger y las 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 obtenidos en el proyecto se resumieron aquí en esta charla de OpenMRS y fueron muy útiles.

Luego, en 2019, se renovó este proyecto y pasamos de los ajustes de la documentación de Swagger a producir variaciones. En su lugar, desarrollamos una documentación estática y fácil de usar en GitHub que ampliaremos en esta temporada de Documentos.

Entonces, un resumen de la propuesta de proyecto actual que quiero describir es :

  1. A continuación, se presentan ejemplos en algunos lenguajes populares (mencionados específicamente como Java y JavaScript).
  2. Se agregó compatibilidad con Playground para la documentación de slate, al igual que la función de "prueba" de Swagger.
  3. Refactorizar y mejorar el trabajo realizado hasta ahora
  4. Buscar y agregar los recursos que faltan
  5. Agregaremos un poco más de descripción a la sección de la consola de los documentos.

DESCRIPCIÓN DETALLADA

  1. Piensa ejemplos en diferentes lenguajes.

Te sugiero agregar ejemplos en Java que se basarán en el SDK y, luego, agregar ejemplos de remodelación que creo que ampliarán nuestra documentación, ya que agregar ejemplos en un lenguaje más como JavaScript no será tan útil como agregar ejemplos de actualización, ya que usé estas APIs de REST mientras trabajaba en el cliente Android de OpenMRS y no había recursos para buscar cada vez que necesite ayuda con los extremos específicamente para Android. Y podría hacer algunos ejemplos de calidad aquí dada mi experiencia trabajando con 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 de agregar ejemplos para las operaciones admitidas, deberíamos agregar ejemplos de autenticación con los servidores de OpenMRS en algunos lenguajes de programación. Por el momento, solo tenemos ejemplos de curl para esto.

  1. Cómo agregar compatibilidad con Playground para probar ejemplos de APIs

He utilizado esta función en la documentación de swagger de OpenMRS alojado 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 las especificaciones de Swagger-UI en la documentación estática actual. Con los botones de activación para ocultar o mostrar el código de documentación de swagger actual que tenemos. De esta manera, incluso podemos asegurarnos de que la función de prueba permanezca activa con las especificaciones actuales de la API. Esta es una de las formas en las que creo que podríamos integrar las funciones de Playground en nuestra documentación estática actual.

  1. Refactorizar y mejorar el trabajo realizado hasta ahora
Verifica los ejemplos actuales de curl

Esta sección es uno de los principales énfasis de este proyecto este año. Por el momento, 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 mantener un documento simple con varios ejemplos de respuestas de curl que obtenemos sobre la ejecución de esas solicitudes curl. Usaré Postman además de la función de pruebas incorporadas en la documentación de Swgger para realizar esta tarea si es necesario.

Faltan respuestas de la API en algunos de los ejemplos.

Se agregaron algunas respuestas a los ejemplos de curl actuales, pero algunos no tienen respuestas. Creo que, aunque las respuestas no sean detalladas, que suele ser el caso de operaciones como borrar definitivamente el recurso, deberíamos tener un ejemplo de respuesta de la API de JSON. Aunque ya documentamos todos los códigos de respuesta posibles y el motivo para obtenerlos, creo que esto haría que los ejemplos de la documentación de la API fueran más uniformes.

Faltan ejemplos de trabajo en varias operaciones

Creo que esta será la parte más importante de la refactorización del 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 ofrece una buena referencia a desarrolladores experimentados, pero deja a los principiantes en un estado de molestia. Como pude deducir de esta publicación de OpenMRS, los buenos ejemplos no tienen precio. Por lo tanto, además de agregar ejemplos de trabajo, podríamos admitir la sintaxis para destacar, que de hecho no es mucho trabajo. Casi todo viene incluido en una 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 la preferencia por la simplicidad y la descripción de los documentos en lugar de una buena IU y una interfaz brillante, me gustaría respetar estos principios y tratar de hacer que los endpoints documentados previamente sean lo más descriptivos posible hablando con los desarrolladores que actualmente trabajan en la API de OpenMRS Webservices y con la participación de la comunidad, tal como lo hice en la publicación de charla para recopilar descripciones de los tipos de atributos de los recursos de los formularios que no eran claros. Trabajaría en las cosas con prudencia al igual que hablar con mis mentores y decidir cuáles son las cosas que realmente agregan valor a los documentos y deben lograrse primero.

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

He visto muchos documentos de APIs solo para aprender y que todos tenían casos de uso como títulos explícitos. Si bien hay casos de uso que no son visibles explícitamente, están de algún modo fusionados dentro de las definiciones y los ejemplos que siguen a las definiciones de los recursos y subrecursos. Creo que deberíamos hacer el esfuerzo de separar los casos de uso como una entidad independiente en la documentación, en lugar de buscarlas en los casos.

  1. Cómo buscar y documentar los recursos que faltan

    El estado actual del proyecto tiene recursos enumerados aquí, pero cuando vi la versión más reciente de la documentación de swagger, pude descubrir muchos recursos que se podrían agregar al conjunto actual de recursos en los documentos de la API compatible con GitHub con la descripción que se logró 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. Trabajo como colaborador activo en el proyecto de cliente de Android en el que interactúo con las APIs a menudo para interactuar con los servidores. Por lo tanto, creo que puedo trabajar bastante bien en este proyecto de extender los documentos de la API, ya que puedo ver mi trabajo como desarrollador y evaluar si realmente facilita el trabajo de otros desarrolladores o no.Ya que me familiaricé con las herramientas que se usan para el repositorio de documentación fácil de usar que se aloja aquí, también hice varias contribuciones a este repositorio para familiarizarme con el repositorio y las herramientas. Por ejemplo, una API de SlateUI sería mejor que la documentación de SlateUI, por lo que sería una mejor API.

Me aseguraré de comunicar el progreso semanalmente con una publicación de debate que ayudará a obtener 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.