La importante tarea de documentar un Software

Documentar el software que compila tiene muchas ventajas. 

La documentación sólida no solo hace que el código sea más fácil de mantener con el tiempo, sino que también resulta más consumible por otros usuarios. Hacer que el código sea más consumible es especialmente importante cuando tiene una API que quieren usar otros usuarios. 

Afortunadamente, existen herramientas y marcos de trabajo que reducen el costo de producción de una buena documentación.

Supongamos que es el jefe de desarrollo para una empresa de enmarcado de láminas. Su empresa decide que sus API estén disponibles públicamente. Muchas de las API no tienen ninguna documentación existente y es su responsabilidad documentarlas. Documentar las API facilitará que los asociados las usen correctamente, lo que dará lugar a unos costos de mantenimiento y asistencia técnica menores.

Necesita documentar cada API de manera fácil y estandarizada, y hospedar la documentación en una ubicación que sea accesible para los asociados.

En este módulo, aprenderá a documentar una API de ASP.NET Core existente, mediante Swagger/OpenAPI, Swashbuckle y Swagger UI.

Una API puede tener gran valor, pero no conseguirá tomar ventaja a menos que los desarrolladores sepan cómo usarla. Los desarrolladores quieren integrar una API tan pronto como puedan. Una buena documentación de API ayuda a los programadores a comprender las capacidades de la API y cómo se debería usar, lo que hace que la integración sea más eficiente.
Tradicionalmente, toda la documentación que describía una API y su uso se escribía a mano. Ahora existen formatos de descripción de API como Swagger/OpenAPI que automatizan el proceso de documentación, lo que facilita a los equipos la tarea de generar, mantener y usar la documentación de API. Describa la API y deje que las herramientas creen documentación enriquecida.

¿Qué es OpenAPI?

OpenAPI es una especificación que se usa para describir las API de REST. Es independiente del idioma y le permite describir la API al completo, incluyendo:

• Puntos de conexión disponibles.
• Parámetros de la operación.
• Métodos de autenticación.
• Datos de contacto y otra información.

Puede escribir las especificaciones de API en YAML o JSON. Con la especificación OpenAPI, tanto personas como equipos pueden comprender las funcionalidades de la API sin tener acceso a su código fuente.

¿Qué es Swagger?

Swagger es un conjunto de herramientas de código abierto creadas en torno a la especificación OpenAPI. Estas herramientas pueden ayudarle a diseñar, compilar y documentar las API de REST. Swagger lo consigue mediante la especificación OpenAPI de la API para comprender su estructura.
Por ejemplo, Swagger UI es una herramienta que puede representar visualmente la documentación en un explorador para una API definida con la especificación OpenAPI. Swagger Codegen puede tomar la misma especificación OpenAPI de una API y generar SDK de cliente.

¿Qué es Swashbuckle?

Swashbuckle es una implementación de Swagger de código abierto utilizada para generar documentación de Swagger para API de .NET Core.
Hay tres componentes principales de Swashbuckle:

• Swashbuckle.AspNetCore.Swagger: este componente es el middleware y el modelo de objetos de Swagger para exponer objetos SwaggerDocument como puntos de conexión JSON.
  
• Swashbuckle.AspNetCore.SwaggerGen: esta biblioteca es un generador de Swagger que genera objetos SwaggerDocument directamente desde sus rutas, controladores y modelos. Se suele combinar con el middleware de punto de conexión de Swagger para exponer automáticamente el JSON de Swagger.
  
• Swashbuckle.AspNetCore.SwaggerUI: este paquete es una versión incrustada de la herramienta Swagger UI. Interpreta el JSON de Swagger para crear una experiencia enriquecida y personalizable para describir la funcionalidad de la API web. Incluye herramientas de ejecución de pruebas integradas para los métodos públicos.