api - open - ¿Cómo enviar encabezados personalizados con solicitudes en Swagger UI?

swagger parameters response

Question

Tengo algunos puntos finales en la API - /user/login , /products .

En Swagger UI publico un correo email y una password para /user/login y, como respuesta, recibo una cadena de token .

Luego, puedo copiar el token de la respuesta y quiero usarlo como valor de encabezado de Authorization en las solicitudes a todas las direcciones URL si está presente, y a /products como ejemplo.

¿Debo crear una entrada de texto manualmente en algún lugar de la página de Swagger UI, luego colocar el token allí y de alguna manera insertar las solicitudes o hay herramientas para administrarlo de una mejor manera?

Answer 1

Aquí hay una respuesta más simple para el combo ASP.NET Core Web Api / Swashbuckle, que no requiere que se registre ningún filtro personalizado. La tercera vez es un encanto que sabes :).

Agregar el siguiente código a su configuración de Swagger hará que aparezca el botón Autorizar, lo que le permitirá ingresar un token de portador para todas las solicitudes. No olvide ingresar este token como Bearer <your token here> cuando se le solicite.

Tenga en cuenta que el código a continuación enviará el token para todas y cada una de las solicitudes y operaciones, que pueden o no ser lo que desea.

public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription) {
    if (operation.parameters == null)
        operation.parameters = new List<Parameter>();


    var attributes = ((System.Web.Http.Controllers.ReflectedHttpActionDescriptor)
        ((apiDescription.ActionDescriptor).ActionBinding.ActionDescriptor)).MethodInfo
        .GetCustomAttributes(false);
    if(attributes != null && attributes.Any()) {
        if(attributes.Where(x => x.GetType() 
            == typeof(MyApiKeyAuthenticationAttribute)).Any()) {

            operation.parameters.Add(new Parameter {
                name = "MyApiKey",
                @in = "header",
                type = "string",
                description = "My API Key",
                required = true
            });
            operation.parameters.Add(new Parameter {
                name = "EID",
                @in = "header",
                type = "string",
                description = "Employee ID",
                required = true
            });
        }
    }


}

A través de este hilo .

Answer 2

DESCARGO DE RESPONSABILIDAD: esta solución no está utilizando el encabezado.

Si alguien está buscando una manera perezosa-perezosa (también en WebApi), sugeriría:

public YourResult Authorize([FromBody]BasicAuthCredentials credentials)

No está recibiendo de cabecera, pero al menos tiene una alternativa fácil. Siempre se puede verificar el objeto en busca de un mecanismo nulo y de retroceso al encabezado.

Answer 3

En ASP.net WebApi, la forma más sencilla de pasar un encabezado a la interfaz de usuario de Swagger es implementar el método Apply (...) en la interfaz IOperationFilter .

Agrega esto a tu proyecto:

public class AddRequiredHeaderParameter : IOperationFilter
{
    public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
    {
        if (operation.parameters == null)
            operation.parameters = new List<Parameter>();

        operation.parameters.Add(new Parameter
        {
            name = "MyHeaderField",
            @in = "header",
            type = "string",
            description = "My header field",
            required = true
        });
    }
}

En SwaggerConfig.cs , registre el filtro desde arriba usando c.OperationFilter <T> () :

    public static void Register()
    {
        var thisAssembly = typeof(SwaggerConfig).Assembly;

        GlobalConfiguration.Configuration 
            .EnableSwagger(c =>
            {
                c.SingleApiVersion("v1", "YourProjectName");
                c.IgnoreObsoleteActions();
                c.UseFullTypeNameInSchemaIds();
                c.DescribeAllEnumsAsStrings();
                c.IncludeXmlComments(GetXmlCommentsPath());
                c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());


                c.OperationFilter<AddRequiredHeaderParameter>(); // Add this here
            })
            .EnableSwaggerUi(c =>
            {
                c.DocExpansion(DocExpansion.List);
            });
    }

Answer 4

En la ASP.NET Core 2 Web API , utilizando el paquete Swashbuckle.AspNetCore 2.1.0, implemente un IDocumentFilter:

SwaggerSecurityRequirementsDocumentFilter.cs

using System.Collections.Generic;
using Swashbuckle.AspNetCore.Swagger;
using Swashbuckle.AspNetCore.SwaggerGen;

namespace api.infrastructure.filters
{
    public class SwaggerSecurityRequirementsDocumentFilter : IDocumentFilter
    {
        public void Apply(SwaggerDocument document, DocumentFilterContext context)
        {
            document.Security = new List<IDictionary<string, IEnumerable<string>>>()
            {
                new Dictionary<string, IEnumerable<string>>()
                {
                    { "Bearer", new string[]{ } },
                    { "Basic", new string[]{ } },
                }
            };
        }
    }
}

En Startup.cs, configure una definición de seguridad y registre el filtro personalizado:

public void ConfigureServices(IServiceCollection services)
{
    services.AddSwaggerGen(c =>
    {
        // c.SwaggerDoc(.....

        c.AddSecurityDefinition("Bearer", new ApiKeyScheme()
        {
            Description = "Authorization header using the Bearer scheme",
            Name = "Authorization",
            In = "header"
        });

        c.DocumentFilter<SwaggerSecurityRequirementsDocumentFilter>();
    });
}

En la interfaz de usuario de Swagger, haga clic en el botón Autorizar y establezca el valor para el token.

Resultado:

curl -X GET "http://localhost:5000/api/tenants" -H "accept: text/plain" -H "Authorization: Bearer ABCD123456"

Answer 5

Para aquellos que usan NSwag y necesitan un encabezado personalizado:

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

    c.AddSecurityDefinition("Bearer", new ApiKeyScheme()
    {
        Description = "JWT Authorization header using the Bearer scheme. Example: /"Authorization: Bearer {token}/"",
        Name = "Authorization",
        In = "header",
        Type = "apiKey"
    });

    c.AddSecurityRequirement(new Dictionary<string, IEnumerable<string>>
    {
        { "Bearer", new string[] { } }
    });

    //...
}

Swagger UI luego incluirá un botón Autorizar .

Answer 6

Puede agregar un parámetro de encabezado a su solicitud, y Swagger-UI lo mostrará como un cuadro de texto editable:

swagger: "2.0"
info:
  version: 1.0.0
  title: TaxBlaster
host: taxblaster.com
basePath: /api
schemes:
- http

paths:

  /taxFilings/{id}:

    get:
      parameters:
      - name: id
        in: path
        description: ID of the requested TaxFiling
        required: true
        type: string
      - name: auth
        in: header
        description: an authorization header
        required: true
        type: string
      responses:
        200:
          description: Successful response, with a representation of the Tax Filing.
          schema:
            $ref: "#/definitions/TaxFilingObject"
        404:
          description: The requested tax filing was not found.

definitions:
  TaxFilingObject:
    type: object
    description: An individual Tax Filing record.
    properties:
      filingID:
        type: string
      year:
        type: string
      period:
        type: integer
      currency:
        type: string
      taxpayer:
        type: object

También puede agregar una definición de seguridad con el tipo apiKey :

swagger: "2.0"
info:
  version: 1.0.0
  title: TaxBlaster
host: taxblaster.com
basePath: /api
schemes:
- http

securityDefinitions:
  api_key:
    type: apiKey
    name: api_key
    in: header
    description: Requests should pass an api_key header.

security: 
 - api_key: []

paths:

  /taxFilings/{id}:

    get:
      parameters:
      - name: id
        in: path
        description: ID of the requested TaxFiling
        required: true
        type: string

      responses:
        200:
          description: Successful response, with a representation of the Tax Filing.
          schema:
            $ref: "#/definitions/TaxFilingObject"
        404:
          description: The requested tax filing was not found.

definitions:
  TaxFilingObject:
    type: object
    description: An individual Tax Filing record.
    properties:
      filingID:
        type: string
      year:
        type: string
      period:
        type: integer
      currency:
        type: string
      taxpayer:
        type: object

El objeto securityDefinitions define esquemas de seguridad.

El objeto de security (llamado "requisitos de seguridad" en Swagger – OpenAPI), aplica un esquema de seguridad a un contexto dado. En nuestro caso, lo aplicamos a toda la API declarando que el requisito de seguridad es un nivel superior. Opcionalmente, podemos anularlo dentro de los elementos y / o métodos de ruta individuales.

Esta sería la forma preferida de especificar su esquema de seguridad; y reemplaza el parámetro de encabezado del primer ejemplo. Desafortunadamente, Swagger-UI no ofrece un cuadro de texto para controlar este parámetro, al menos en mis pruebas hasta ahora.

Answer 7

También es posible usar el atributo [FromHeader] para los parámetros de los métodos web (o propiedades en una clase de modelo) que deben enviarse en encabezados personalizados. Algo como esto:

[HttpGet]
public ActionResult Products([FromHeader(Name = "User-Identity")]string userIdentity)

Al menos funciona bien para ASP.NET Core 2.1 y Swashbuckle.AspNetCore 2.5.0.

Answer 8

Terminé aquí porque intentaba agregar condicionalmente parámetros de encabezado en la interfaz de usuario de Swagger, en base a mi propio atributo [Authentication] que agregué a mi método API. Siguiendo la sugerencia que @Corcus incluyó en un comentario, pude derivar mi solución y espero que ayude a otros.

Usando Reflection, es verificar si el método anidado en la apiDescription tiene el atributo deseado (MyApiKeyAuthenticationAttribute, en mi caso). Si lo hace, puedo anexar los parámetros de encabezado deseados.

app.UseSwaggerUi3(typeof(Startup).GetTypeInfo().Assembly, settings =>
      {
          settings.GeneratorSettings.IsAspNetCore = true;
          settings.GeneratorSettings.OperationProcessors.Add(new OperationSecurityScopeProcessor("custom-auth"));

          settings.GeneratorSettings.DocumentProcessors.Add(
              new SecurityDefinitionAppender("custom-auth", new SwaggerSecurityScheme
                {
                    Type = SwaggerSecuritySchemeType.ApiKey,
                    Name = "header-name",
                    Description = "header description",
                    In = SwaggerSecurityApiKeyLocation.Header
                }));
        });            
    }