Creación de documentación de API
La creación de documentación de API para el repositorio de código fuente es muy importante. Una buena documentación ayuda a los desarrolladores a comprender, mantener y usar fácilmente la API. En la documentación completa se explica cómo funciona la API, qué entradas necesita, qué salidas proporciona y cómo usar los puntos de conexión de API. Al crear documentación de API, debe elegir el mejor formato (como la especificación openAPI o Markdown), incluir ejemplos y escenarios de uso, mantenerlo actualizado cuando cambie el código y pedir a los usuarios de api que hagan que sea mejor. Aunque el enfoque general de la documentación de api funciona en todas partes, hay algunas diferencias entre Azure DevOps y GitHub.
Creación de documentación de API en Azure DevOps
Para agregar documentación de API a un proyecto de Azure DevOps de forma eficaz, debe usar una herramienta de documentación dedicada que funcione con el flujo de trabajo de desarrollo. Entre las opciones más populares se incluyen Swagger (OpenAPI), API Blueprint y sistemas de documentación basados en Markdown, como MkDocs o Docusaurus. Su integración de Azure DevOps ayuda a automatizar la creación de documentación y a mantenerla sincronizada con el código. La mayoría de las herramientas de documentación también pueden leer comentarios insertados e incluirlos en la documentación generada automáticamente.
Debe publicar la documentación de la API en una ubicación central a la que puedan acceder los miembros del equipo y las partes interesadas. Podría tratarse de un sitio web de documentación dedicado, una wiki en Azure DevOps o un portal de documentación externo.
También puede usar anotaciones de código o decoradores directamente en el código para agregar metadatos que describen los puntos de conexión de API. Herramientas como Swagger Codegen o Springfox pueden procesar estas anotaciones y crear archivos de especificación de OpenAPI.
Configure procesos automatizados en Azure Pipelines para crear documentación de API automáticamente cada vez que haya un cambio en el código. Esto garantiza que la documentación permanezca actualizada y refleje los cambios más recientes en las API.
Creación de documentación de API en GitHub
Al usar GitHub, considere la posibilidad de crear documentación de API mediante herramientas que forman parte del ecosistema de GitHub.
Empiece por documentar los puntos de conexión de 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, ya que es ampliamente compatible y fácil de usar. Defina una estructura coherente para documentos individuales, dividiendo cada uno en secciones que describen 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 usar generadores de documentación o generadores de sitios estáticos para facilitar el proceso de creación de documentación de API a partir de archivos Markdown. Entre las opciones populares se incluyen Jekyll, MkDocs, Docusaurus y Hugo. Configure el generador para leer archivos Markdown y crear páginas HTML estáticas. Puede personalizar el diseño, el tema y el estilo para que coincidan con la personalización de marca y las preferencias del proyecto.
Para publicar el contenido HTML, use GitHub Pages, que permite hospedar sitios web estáticos directamente desde el repositorio de GitHub. Puede crear una rama dedicada para este propósito e insertar los archivos HTML en esta rama. También puede usar 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.
Configure 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. Configure el flujo de trabajo de automatización para crear los archivos de documentación HTML mediante el generador de documentación elegido e implementarlos en GitHub Pages.