Sacando provecho de Swagger - parte 3

por Antonio Cárdenas García 25 de Mayo del 2021 · 5 mins.

Ya tenemos el tercer post de la serie, ya hemos visto comentarios XML y los ISchemaFilter. Hoy veremos content-type y headers.

Recordamos que tenemos una API en asp.net core 3.1 y con la versión de Swashbuckle.AspNetCore 5.0.0.

Fijar content type application/json

Si nuestra API solo va a aceptar y devolver contenido de tipo json, es recomendar fijar estos parámetros. Para ello utilizamos los atributos ‘Consumes’ y ‘Produces’ de Microsoft.AspNetCore.Mvc.

  
    /// 

    /// Get example info.
    /// 
    /// Example id.</param>
    /// Request example</param>
    /// 
    [HttpPatch("/example/{id}")]
    [Consumes("application/json")]
    [Produces("application/json")]
    public ActionResult< ExampleResponse > GetExample(int id, [FromBody] ExampleRequest request) 
    => Ok(new ExampleResponse());

En este caso se han aplicado a nivel de método como caso de prueba, sería más habitual aplicarlos a toda la API.

Añadir Headers personalizados

En ocasiones tenemos que construir una API que tiene que contar con un header propio, en este caso hemos utilizado un IOperationFilter y lo aplicamos a todos los endpoints.

  
public class CustomHeaderFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        if (operation.Parameters == null)
            operation.Parameters = new List< OpenApiParameter >();

        operation.Parameters.Add(new OpenApiParameter
        {
            Name = "x-header",
            In = ParameterLocation.Header,
            Description = "Custom header for our application.",
            Required = true,
            Schema = new OpenApiSchema
            {
                Type = "string",
                Example = new OpenApiString(CustomHeader.Xyz.ToString()),
                Enum = Enum
                    .GetValues(typeof(CustomHeader))
                    .Cast< CustomHeader >()
                        .Select(x => OpenApiAnyFactory.CreateFor(new OpenApiSchema() { Type = "string" }, x.ToString()))
                        .ToList()
            }
        });
    }
}

Para guardar los valores del CustomHeader se ha utilizado un enum:

  
public enum CustomHeader
{
    Xyz,
    Abc
}

Y ya que tenemos un Enum, podemos ajustar NewtonsoftJson para serializar los enums como string. Para ello desde el Startup, en el método ConfigureServices podemos añadir:

  
services
    .AddControllers()
    .AddNewtonsoftJson(options =>
    {
        options.SerializerSettings.Converters.Add(new StringEnumConverter());
    });

Una vez creado el IOperationFilter, igual que el resto de filtros de swagger, es necesario registraro como hemos hecho con el filtro anterior:

  
services.AddSwaggerGen(c =>
{
    //[...]

    c.OperationFilter< CustomHeaderFilter >();

    //[...]
});

De esta forma, cuando swagger se encuentre el enum de CustomHeader nos facilitará un desplegable con los distintos valores:

Muchas gracias. Nos leemos en más artículos.