Vamos a empezar una serie de posts dedicados a sacar más provecho a Swagger y darle más valor a nuestra API.
Una vez hemos creado nuestra API y ya tenemos swagger instalado y funcionando, es buen momento para añadir más información y hacerlo más útil y usable. En concreto, el ejemplo se ha realizado con Visual Studio 2019, con una API en asp.net core 3.1 y con la versión de Swashbuckle.AspNetCore 5.0.0.
Comentarios XML
El primer paso sería habilitar los comentarios XML. Esto nos servirá para añadir a cada endpoint información adicional:
///
/// Get example info.
///
/// Example id.</param>
///
Para que se lean y muestren los summaries en swagger primero tenemos que agregar unas líneas en el csproj del projecto de la API:
true
No obstante, esto nos provocará un incómodo warning en cada método que no tenga summary:
Para que no aparezcan estos warngins los podemos deshabilitar añadiendo una línea más al anterior código del PropertyGroup:
true $(NoWarn);1591
Ahora que hemos configurado la generación de los xml, tenemos que añadirlos en la configuración del swagger.
Para ello, en el Startup al configurar AddSwaggerGen añadiremos las siguientes líneas:
services.AddSwaggerGen(c =>
{
//[...]
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
//[...]
});
De esta forma, nos aparecerá está información cuando vayamos a llamar al endpoint en cuestión:
En este punto, es interesante aprovechar para especificar las respuestas de dicho endpoint. Para ello podemos utilizar el atributo ProducesResponseTypeAttribute especificando los HttpStatusCodes que devolvemos. Adicionalmente, también se puede especificar un mensaje concreto para cada código de respuesta añadiendo tags ‘response’ en el summary:
///
/// Get example info.
///
/// Example id.</param>
/// Ok response.
/// Custom response for 403.
[HttpGet("/example/{id}")]
[ProducesResponseType(typeof(int), (int)HttpStatusCode.OK)]
[ProducesResponseType(typeof(ErrorResponse), (int)HttpStatusCode.BadRequest)]
[ProducesResponseType(typeof(ErrorResponse), (int)HttpStatusCode.Unauthorized)]
[ProducesResponseType(typeof(ErrorResponse), (int)HttpStatusCode.Forbidden)]
[ProducesResponseType(typeof(ErrorResponse), (int)HttpStatusCode.NotFound)]
public IActionResult GetExample(int id) => Ok(id);
Con esto, ahora swagger nos mostrará, además de la response (200 - Success) que hemos visto antes, un ErrorResponse para los códigos 400, 401, 403 y 403. Y en concreto, un mensaje personalizado para el código 200 y para el 403. .
A las respuestas de error, le hemos añadido un tipo de respuesta propio (ErrorResponse) no es obligatorio, pero es recomendable.
