Creación de documentación de API
Documentar la API de un repositorio de código fuente es esencial para proporcionar claridad, accesibilidad y facilidad de uso a los desarrolladores que mantienen y consumen la API. La documentación completa sirve de guía para comprender la funcionalidad, las entradas, las salidas y el uso de los puntos de conexión de la API. Al documentar la API, debe seleccionar el formato de presentación más adecuado (como la especificación OpenAPI o Markdown), incluir ejemplos y escenarios de uso, mantenerla actualizada con los cambios en el código y solicitar comentarios a los consumidores de la API para mejorar continuamente su calidad.
Aunque el enfoque general para documentar la API es independiente de la plataforma, existen algunas diferencias en su implementación entre Azure DevOps y GitHub.
Documentación de la API en Azure DevOps
Para agregar documentación de API a un proyecto Azure DevOps de la manera más eficiente, debe considerar la utilización de una herramienta o plataforma de documentación dedicada que se integre con su flujo de trabajo de desarrollo. Las opciones más populares en esta categoría incluyen Swagger (OpenAPI), API Blueprint y sistemas de documentación basados en Markdown como MkDocs o Docusaurus. Sus capacidades de integración de Azure DevOps ayudan a automatizar el proceso de generación de documentación, manteniéndolo sincronizado con el código base. La mayoría de las herramientas de documentación también permiten analizar los comentarios en línea e incluirlos en la documentación generada automáticamente.
Debe publicar la documentación de la API en una ubicación central accesible para los miembros de su equipo y las partes interesadas. Puede tratarse de un sitio web de documentación dedicado, una wiki dentro de Azure DevOps o un portal de documentación externo.
Como alternativa, puede utilizar anotaciones de código o decoradores directamente dentro de su código para agregar metadatos que describan sus puntos de conexión de la API. Herramientas como Swagger Codegen o Springfox son capaces de procesar estas anotaciones y generar los archivos de especificación OpenAPI.
Configure procesos automatizados dentro de sus Azure Pipelines para generar documentación de API automáticamente cada vez que se produzca un cambio en la base de código. Esto garantiza que su documentación se mantenga actualizada y refleje los últimos cambios en sus API.
Documentación de la API en Github
Cuando utilice GitHub, considere la posibilidad de generar documentación de API aprovechando las herramientas que forman parte del ecosistema de GitHub.
Empieza por documentar los puntos de conexión de la API, las operaciones, los parámetros, las respuestas y cualquier otra información pertinente. Considere la posibilidad de crear esa documentación en formato Markdown para tener en cuenta su amplio apoyo y facilidad de uso. Definir una estructura coherente de los documentos individuales, dividiendo cada uno en secciones que describan la autenticación, los puntos de conexión, los parámetros de solicitud, los ejemplos de respuesta, etc.
Al igual que con Azure DevOps, puede utilizar generadores de documentación o generadores de sitios estáticos para agilizar el proceso de generación de documentación de API a partir de archivos Markdown. Las opciones más populares son Jekyll, MkDocs, Docusaurus y Hugo. Configure el generador para analizar archivos Markdown y generar páginas HTML estáticas. Puede personalizar el diseño, el tema y el estilo para adaptarlos a la marca y las preferencias de su proyecto.
Para publicar el contenido HTML, aprovecha GitHub Pages, que permite hospedar sitios web estáticos directamente desde tu repositorio de GitHub. Puede crear para este fin una rama dedicada y insertar los archivos HTML en esta rama. También puede implementar Acciones de GitHub para compilar e implementar automáticamente la documentación de su API cada vez que se produzca un cambio en los archivos de documentación o en el código base.
Configura Acciones de GitHub para compilar e implementar automáticamente la documentación de la API siempre que haya un cambio en los archivos de documentación o en el código base. Configure el flujo de trabajo de automatización para generar los archivos de documentación HTML utilizando el generador de documentación elegido e impleméntelos en GitHub Pages.