Documentación de API

Introducción

La documentación de las API es un tema extremadamente importante y no debe descuidarse a la hora de crear servicios web. Más allá del aspecto puramente de "buena práctica de desarrollo", esta documentación debe permitir a cualquier persona o servicio entender el uso del API desarrollado, cómo explotarlo, qué datos se devolverá, qué acciones se llevarán a cabo y, en definitiva, cuál será el resultado de la llamada.

Afortunadamente, el estándar HTTP y los principios REST proporcionan un buen marco para los elementos técnicos de un API web: código de retorno, ruta HTTP, variables con nombre, tipo de acción HTTP, cabeceras de solicitud y respuesta, etc. Sin embargo, estos elementos no son necesariamente visibles de forma inmediata cuando el desarrollador quiere utilizar un API. Por ejemplo, la ruta de un API es directamente visible porque el desarrollador debe utilizarla para realizar la llamada, pero el código de retorno no es accesible hasta que se ha realizado la llamada. La documentación describe todos estos elementos, lo que facilita la vida a los usuarios del API.

Para escribir fácilmente esta documentación, el desarrollador tiene a su disposición todo un conjunto de herramientas, estándares y prácticas fácilmente accesibles y utilizables en sus tareas de documentación....

La herramienta Swagger y el estándar Open API

Históricamente, Swagger era el nombre que se daba a las herramientas y estándares utilizados para documentar las API. Hoy en día, las herramientas llamadas Swagger están separadas del estándar, que ahora se llama Open API. Este mismo estándar fue construido y escrito por los equipos de Swagger. Swagger es un conjunto de herramientas de código abierto y comerciales desarrolladas por SmartBear Software, pionera en el campo de la calidad del software, especialmente con las herramientas SoapUI y QAComplete.

Swagger crea varias herramientas de código abierto para desarrolladores y diseñadores de APIs. La primera herramienta interesante es Swagger Codegen. El principio es sencillo: a partir de un archivo Open API, Swagger Codegen es capaz de generar un servidor web -que expone el API descrito- y un cliente que permite llamar al servidor y cumplir el contrato de interfaz del API. En concreto, esta herramienta acelera la generación de SDK para las API que desarrollan las empresas, de modo que los equipos se pueden centrar en las API y en su adopción. El código generado puede estar en varios lenguajes y frameworks: .NET, PHP, Python, Java, JavaScript, etc.

He aquí un ejemplo de especificación de Open API utilizada para generar una API para artículos:

openapi: 3.0.0  
info:  
 title: Articles API  
 version: 1.0.0  
servers:  
 - url: http://localhost:8080/api/v1  
paths:  
 /articles:  
   get:  
     description: Recuperación la lista de artículos 
     responses:  
       200:  
         description: La lista de artículos  
         content:  
           application/json:  
             schema:  
               type: array  
              items:  ...

Integración en controladores

Swagger se puede integrar fácilmente en una solución ASP.NET Core, en particular añadiendo atributos a los controladores de API de los proyectos web. Para empezar, necesitamos añadir el paquete NuGet que nos permite utilizar Swagger dentro de nuestro proyecto.

dotnet add package Swashbuckle.AspNetCore 

A continuación, debe configurar el proyecto en el archivo Startup.cs y más concretamente en el método ConfigureServices con el siguiente código:

public void ConfigureServices(IServiceCollection services)  
{  
   services.AddSwaggerGen(c =>  
   {  
       c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API",  
Version = "v1" });  
   });  
   services.AddControllers();  
} 

El método AddSwaggerGen añade todos los servicios necesarios para generar la documentación en el proyecto. A continuación, es posible añadir varias documentaciones (versión, conjunto de API, etc.) y el objeto OpenApiInfo se puede utilizar para especificar alguna información específica de cada documentación. Esto significa que es posible - en un solo proyecto web - generar varias documentaciones de API según sus necesidades....

Swagger UI y documentación interactiva

Swagger UI es una herramienta de código abierto que genera una interfaz de usuario para visualizar e interactuar con una API REST documentada con OpenAPI. Swagger UI proporciona una interfaz de usuario basada en navegador para explorar las API documentadas, ejecutar solicitudes y ver las respuestas.

La especificación OpenAPI puede estar en formato JSON o YAML. La herramienta admite operaciones CRUD estándar (GET, POST, PUT, DELETE), así como otros tipos de operaciones personalizadas, cabeceras de autorización personalizadas, parámetros de consulta, así como contenidos de consulta, opciones de paginación y mucho más.

Con Swagger UI, los desarrolladores pueden entender rápidamente cómo utilizar e interactuar con un API, sin tener que escribir código ni configurar herramientas externas. Esto facilita enormemente la adopción del API y mejora la experiencia del usuario.

Para añadir Swagger UI a un proyecto ASP.NET Core, basta con añadir el siguiente código...