Documentar una API web de ASP.NET Core con herramientas de Swagger

  • 5 minutos

Una API puede tener gran valor, pero no consigue 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 tenemos una especificación estándar para las descripciones de API denominada OpenAPI. Swagger UI proporciona herramientas de implementación y prueba de la especificación OpenAPI para sus API. Swashbuckle es un paquete de código abierto que proporciona la generación automática de documentos de descripción OpenAPI directamente desde los controladores de la API web utilizando la reflexión .NET. Swashbuckle le ayuda a automatizar el proceso de descripción, lo que facilita a los equipos la generación, el mantenimiento y el uso de la documentación de la API basada en OpenAPI. 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, incluido lo siguiente:

  • 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 usa 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 mediante la reflexión de .NET.

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. La biblioteca 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.

  • CLI de Swashbuckle: Una vez instalada, esta herramienta global de .NET permite generar especificaciones OpenAPI durante la compilación o publicación. Hay un vínculo para descargar la CLI de Swashbuckle al final de este módulo.

Puesto que estas bibliotecas se agregan a la aplicación, generan y visualizan la documentación de API de la versión más reciente de la API. Crean documentación viva, sincronizada en todo momento con el código más reciente.