Comment envoyer des en-têtes personnalisés avec des demandes dans l'interface utilisateur Swagger?

J'ai quelques points de terminaison dans l'API - /user/login/products.

Dans Swagger UI je poste email et password à /user/loginet en réponse je reçois un token chaîne.

Alors, je peux copier le jeton de la réponse et vous voulez l'utiliser comme Authorization valeur d'en-tête dans les demandes pour toutes les url si elle est présente, et à /products comme un exemple.

Dois-je créer une entrée de texte manuellement quelque part sur le Style de l'INTERFACE utilisateur de la page, puis de mettre le jeton et d'une certaine injecter dans les demandes ou il y a des outils pour les gérer au mieux?

source d'informationauteur Sergei Basharov

Vous pouvez ajouter un paramètre d'en-tête à votre demande, et Swagger-UI va le montrer comme une zone de texte modifiable:

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

Comment envoyer des en-têtes personnalisés avec des demandes dans l'interface utilisateur Swagger?

Vous pouvez également ajouter une définition de la sécurité avec le type 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

La securityDefinitions objet définit les régimes de sécurité.

La security objet (appelé "exigences de sécurité" dans Swagger–OpenAPI), s'applique à un régime de sécurité à un contexte donné. Dans notre cas, nous allons l'appliquer à l'ensemble de l'API en déclarant la sécurité de l'exigence d'un haut niveau. On peut éventuellement le remplacer au sein de chaque élément de chemin d'accès et/ou de méthodes.

Ce serait la meilleure façon de spécifier votre régime de sécurité; et il remplace le paramètre d'en-tête de la premier exemple. Malheureusement, Swagger-UI n'offre pas une zone de texte pour contrôler ce paramètre, au moins dans mon test, jusqu'à présent.

Sur ASP.net WebApi, de la façon la plus simple de passer-en un en-tête sur Swagger UI est de mettre en œuvre Appliquer(...) méthode sur IOperationFilter interface.

L'ajouter à votre projet:

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
        });
    }
}

Sur SwaggerConfig.csenregistrer le filtre à partir de ci-dessus à l'aide de 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);
            });
    }

Dans ASP.NET Core 2 Web APIà l'aide de Swashbuckle.AspNetCore paquet 2.1.0, de mettre en œuvre 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 Démarrage.cs, configurer une définition de la sécurité et d'enregistrer le filtre personnalisé:

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>();
    });
}

À Swagger de l'INTERFACE utilisateur, cliquez sur Autoriser bouton et réglez la valeur du jeton.

Comment envoyer des en-têtes personnalisés avec des demandes dans l'interface utilisateur Swagger?

Résultat:

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

J'ai atterri ici parce que j'essayais de conditionnellement ajouter des paramètres d'en-tête dans le Style de l'INTERFACE utilisateur, basée sur ma propre [Authentication] attribut j'ai ajouté à ma méthode de l'API. Suivant le soupçon que @Corcus répertoriés dans un commentaire, j'ai été en mesure de tirer ma solution, et j'espère que ça aidera d'autres personnes.

L'aide de la Réflexion, c'est de vérifier si la méthode imbriquée dans apiDescription a l'attribut souhaité (MyApiKeyAuthenticationAttribute, dans mon cas). Si elle le fait, je peux ajouter mon choix paramètres d'en-tête.

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
            });
        }
    }


}

Pour ceux qui utilisent NSwag et ont besoin d'un en-tête personnalisé:

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
                }));
        });            
    }

Swagger de l'INTERFACE utilisateur sera alors inclure une Autoriser bouton.

Vous devez vous connecter pour publier un commentaire.