No hace mucho tiempo cuando los desarrolladores escuchábamos la palabra documentación, lo primero que se nos venía a la mente eran pilas de hojas de cálculo, documentos, correos, cuadernillos y mucho trabajo manual, es entonces que esbozando un gesto de lamento decíamos pues, que se le va a hacer, hay que hacerlo, o mejore que lo haga el practicante!. Puede que hasta hoy suceda eso, en muchos centros de trabajo, pero no tiene porqué ser así, veamos cómo documentar los métodos y propiedades de un API.
De la forma en que se hacía antes, que era haciendo la documentación de forma manual, podemos extraer al menos dos grandes desventajas:
- Al ser estática la documentación, tiende a quedar obsoleta, imaginemos por ejemplo que el método PagarBoleto ahora ya no devuelve un valor booleano, sino que ahora retorna un objeto de la clase Boleta, si no estamos atentos la documentación quedará obsoleta y esto puede tener consecuencias graves.
- Requiere dedicación y tiempo, recursos que sin dudas son escasos y preciados, ya que como vimos en el punto anterior hay que estar atentos a cualquier cambio.
Entonces aquí es donde una herramienta llamada Swagger entra en escena, asumo que hay otras herramientas allá afuera, pero en esta ocasión me voy a concentrar en esta ya que es la que estoy utilizando actualmente y me parece muy buena, siéntete libre de comentar la herramienta que tu usas y le echamos un ojo.
Conociendo la herramienta
La página oficial de swagger es https://swagger.io/ y ella misma lo define así: Swagger es el ecosistema de herramientas más utilizado para diseñar, desarrollar, testear y documentar API's con la especificación OpenAPI (OAS).
Como podemos notar, Swagger es mucho más que un documentador, pero aquí descubriremos un poco más sus funciones como documentador, a continuación describo algunas de sus características que me parecen más relevantes:
- Es dinámico, si tu API cambia, la documentación también lo hará
- Te permite manejar varias versiones de API y cada una con su documentación
- Te provee de toda una interfaz gráfica robusta de documentación sin que tengas que programarla
- En la misma documentación te permite testear los métodos HTTP
- Te genera mockups de los objetos json que necesitan tus métodos de tu API
- Fácil integración con tu código, aquí integraremos Swagger con un API hecho con .Net Core
Empecemos a usar Swagger
Pues bien, manos a la obra cracks, lo que haremos será integrar swagger con un API hecho en .Net Core, esto será lo que deberás hacer en el proyecto que quieras documentar, haciéndole unos pequeños ajustes según tus necesidades:
El proyecto del API en .Net Core fue el que hicimos en la entrada anterior, aquí el link https://bravedeveloper.com/2021/07/20/entendiendo-los-web-api-con-net-core-y-entity-framework/, y aquí el repo en Github (en el commit 59a491d) para que lo descargues y le apliques Swagger. Te recomiendo que primero leas la entrada mencionada y la hagas tu mismo, luego la documentas 😉
Para que el proyecto o repo que bajaste funcione deberás configurar bien tu cadena de conexión la cual esta en el archivo appsettings.Development.json y luego ejecutar el comando update-database desde el package manager console, de forma que se ejecuten las migraciones hacia tu base de datos.
Instalando dependencias
Desde Nuget instalar:
- Swashbuckle.AspNetCore
Configurar Startup.cs
En primer lugar debes asegurarte de activar el siguiente checkbox y configurar bien la ruta del archivo de configuración xml de Swagger.
Fíjate que la ruta sea la raiz del proyecto, en caso te hayas descargado mi repo de github actualiza la ruta sino te dará error de compilación o dejarán de funcionar algunas cosas en la documentación
En todo proyecto de .Net Core existe una clase llamada Startup que es la que contiene las instrucciones de configuración de servicios y middlewares, pues vamos a agregar una lineas a su método ConfigureServices:
public void ConfigureServices(IServiceCollection services)
{
...
//Configuraciones de Swagger
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
services.AddSwaggerGen(config =>
{
config.SwaggerDoc("v1",
new Microsoft.OpenApi.Models.OpenApiInfo() //Swashbuckle.AspNetCore.Swagger.info() se usa en versiones anteriores
{
Title = "Ejemplo de swagger",
Description = "Esta es una documentación de swagger, aquí tambien puede ir información necesaria para utilizar el Api, etc..."
}
);
config.IncludeXmlComments(xmlPath);//Configuramos los comentarios en los controladores
});
}
Y ahora configuramos el Middleware, es decir el método Configure:
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseHttpsRedirection();
app.UseRouting();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});
//Configuración de middleware
app.UseSwagger();
app.UseSwaggerUI(config =>
config.SwaggerEndpoint("/swagger/v1/swagger.json","API SWAGGER!")
);
}
Configurando los controladores
Para utilizar la documentación se tiene que agregar data anotations, o una especie de comentarios (pero con tres barras) antes de cada controlador mediante el cual mediante nodos le indicaremos valores que queremos que aparezcan en la documentación, sin embargo Swagger por su parte agregará de forma automática también información de cada método, veamos por ejemplo el caso del controlador siguiente:
Escribiendo /// (tres barras inclinadas) se autocompletarán algunos campos básicos, inténtalo crack
/// <summary>
/// Este método trae todos los autores
/// </summary>
/// <returns>Puros autores</returns>
/// <remarks>Este es un remark para información ampliada de autores de libros comunes y conocidos.</remarks>
/// <response code="200">Todo bien eh</response>
/// <response code="400">La liaste ah</response>
[HttpGet]
public async Task<ActionResult<List<Autor>>> Get()
{
return await context.Autor.Include(x=>x.Libros).ToListAsync();
}
El resultado de esto es el siguiente:
Ahora abriré un método y resaltaré los campos que yo puse en el controlador, nota como te hace la vida más fácil documentando una descripción corta, una mas detallada y los responses:
Como habrás notado al pulsar "Try it out" podrás ejecutar los métodos en esta misma página, lo que haces por ejemplo con Postman, lo puedes hacer directamente desde aquí también 😊
En aquellos controladores que tengan parámetro de tipo primitivo (int, string, double) se nos creará textboxes:
En los parámetros de tipo complejo se nos creará un mockup de json con info de ejemplo para facilidad nuestra, veamos:
Configurando las entidades
De las dos entidades que tengo en el proyecto, configuraré una propiedad de la entidad Autor:
public class Autor
{
/// <summary>
/// Este es el identificador de un autor
/// </summary>
public int Id { get; set; }
public string Nombre { get; set; }
public List<Libro> Libros { get; set; } //propiedad de navegación
}
Al agregar summary, le estoy diciendo a Swagger, muéstrame esta info en la documentación que orientará mejor al usuario y le dirá que significa este campo:
En conclusión...
Como has podido apreciar, Swagger te facilita bastante la documentación de tu API, ahora el equipo frontend tendrá siempre la documentación actualizada y se evitarán tener que estar cambiando a cada momento los archivos, o decir, ¡lo siento, me olvidé de decirte que ahora el json no devuelve un número sino una colección! y gracias a Swagger, quiero agradecer al buen Alberto Picazo quien me ayudó a entender más esta herramienta, te recomiendo visitar su canal de Youtube, y sigue investigando crack!
Comparte este contenido 😊
Hola buen día
Estoy buscando la soluciòn para que en el schema de Swagger se vea reflejado el valor default de un campo.
Tal vez me puede ayudar.
Copio una clase de ejemplo y luego còmo lo veo en Swagger:
public class Prueba
{
[RegularExpression(«BU|DU»)]
public string Comprobante { get; set; } = «BU»;
}
Swagger me muestra lo siguiente:
comprobante string
minLength: 1
pattern: BU|DU
Lo que quisiera que Swagger me muestre es el valor default del campo, el cual en la clase figura como = «BU»;
Es decir, poder ver que el default es BU
Quisiera no tener que hacerlo mediante el uso de summary
saludos y gracias
Daniel