Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.
Resumen del proyecto
- Organización de código abierto:
- OpenMRS
- Escritor técnico:
- Saurab
- Nombre del proyecto:
- Extensión de la documentación fácil de usar de GitHub para la API de REST
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Objetivo principal
Mejorar la documentación de la API de REST basada en OpenMRS Swagger 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 hay 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 debemos extender 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 di cuenta de 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 de REST de OpenMRS, mejorando su especificación Swagger y mejorando la forma en que se genera su especificación Swagger para generar una mejor versión de la documentación propiamente dicha. Todos los detalles relevantes obtenidos en el proyecto se resumieron aquí en esta publicación de charla de OpenMRS y fueron bastante útiles.
Luego, en 2019, se renovó este proyecto y pasamos de los ajustes de la documentación de Swagger que produjeron variaciones de esto. En su lugar, desarrollamos una documentación estática que es compatible con GitHub y que extenderemos en esta temporada de Documentos.
Por lo tanto, un resumen de la propuesta de proyecto actual que voy a describir es :
- Idear ejemplos en algunos lenguajes populares (mencionados específicamente con Java y JavaScript).
- Se agregó compatibilidad con Playground para la documentación de slate al igual que la función de "prueba" de Swagger.
- Refactorizar y mejorar el trabajo realizado hasta ahora
- Cómo encontrar y agregar los recursos que faltan.
- Agregamos un poco más de descripción a la sección de documentos de la consola.
DESCRIPCIÓN DETALLADA
- Piensa en ejemplos en diferentes lenguajes.
Sugiero agregar ejemplos en Java, que se basará en un SDK, y luego agregar ejemplos de mejoras que creo que aportará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 mejoras, ya que usé estas APIs de REST mientras trabajaba en el cliente OpenMRS para Android y no había recursos para buscar cada vez que necesitaba ayuda con los extremos específicamente para Android. Además, podría hacer algunos ejemplos de calidad aquí, dada mi experiencia modificando extremos de la API de OpenMRS en el cliente de Android. Analizaré esto con mis mentores y trabajaré en lo que se decida. Además de agregar ejemplos para las operaciones admitidas, también debemos agregar ejemplos de autenticación con servidores OpenMRS en algunos lenguajes de programación. En este momento, solo tenemos ejemplos de curl para esto.
- Cómo agregar compatibilidad con Playground para probar ejemplos de API
Usé esta función en la documentación de swagger de OpenMRS alojado en el servidor de demostración y es una herramienta muy conveniente 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. El uso de los botones de activación de Show visibles y el uso del 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.
- 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. 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 verificar directamente desde el navegador. Probaré todos los extremos actuales y mantendré un documento simple con varias respuestas de ejemplos de curl que obtenemos cuando ejecutamos esas solicitudes curl. Usaré Postman además de la función de prueba incorporada en la documentación con swagger 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 de los ejemplos de curl no tienen respuestas. Creo que, aunque las respuestas no sean 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 documentamos todos los códigos de respuesta posibles y el motivo para obtenerlos. Creo que esto haría que los ejemplos en la documentación de la API sean 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 los desarrolladores experimentados, pero deja a los principiantes en un estado de molestia. Como pude deducir de esta publicación de OpenMRS, los buenos ejemplos son invaluables, por lo que, además de agregar ejemplos de trabajo, podríamos admitir el resaltado de la sintaxis, que, de hecho, es poco trabajo. En general, 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 en los documentos en lugar de una buena IU y una interfaz brillante, seguiría estos principios y trataría de hacer que los extremos documentados previamente fueran lo más descriptivos posible hablando con los desarrolladores que actualmente trabajan en la API de OpenMRS Webservices e interactuando con la comunidad, tal como lo hice en la publicación de charla para recopilar descripciones de los tipos de atributos para los recursos de los formularios que no eran claros. Realmente me dedicaría a las cosas con prioridad, hablar con mis mentores y decidir cuáles son las cosas que realmente agregan valor a los documentos y deben lograrse primero.
Agrega casos de uso como un título explícito
He visto mucha documentación de API solo para aprender a usarla y vi que todos tenían casos de uso como títulos explícitos, aunque hay casos de uso que no están visibles de forma explícita, están 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 los casos, en lugar de inferir las definiciones.
Encuentra y documenta los recursos que faltan
El estado actual del proyecto tiene recursos que se enumeran aquí, pero cuando vi 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 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 en este proyecto de extender los documentos de la API bastante bien, ya que puedo ver mi trabajo como desarrollador y evaluar si realmente facilita el trabajo de otros desarrolladores o no. Me familiaricé con las herramientas usadas para el repositorio de documentación fácil de usar que se aloja aquí y también realicé varias contribuciones a este repositorio para familiarizarme con el repositorio y las herramientas; es decir, me gustaría que la API mejorara con SlateUI.
Me aseguraré de comunicar el progreso semanalmente con una publicación de charla que ayudará a obtener comentarios de la comunidad y a trabajar en estrecha correlación con mi mentor y la comunidad para aprovechar al máximo este período de documentación.