Interfejs użytkownika Swagger: przekazywanie niestandardowego nagłówka autoryzacji

Question

Używam Swashbuckle i Swagger w interfejsie API sieci ASP.NET. Próbuję znaleźć sposób przekazania nagłówka autoryzacji zawierającego token na okaziciela przez interfejs Swagger. Szukałem w pobliżu, ale wszystkie odpowiedzi wydają się wskazywać na link this.

Zakłada się jednak, że treść nagłówka jest znana z góry. Naprawdę potrzebuję sposobu na zmianę nagłówka w interfejsie użytkownika Swagger (tuż przed naciśnięciem przycisku "Wypróbuj!"), Ponieważ token Okaziciela wygasa co godzinę. Coś podobnego do sposobu, w jaki Postman pozwala dodawać nagłówki.

Wydaje się, że jest to tak absurdalnie prosty problem, ale jaka jest odpowiedź?

Answer 1

Wpadliśmy na ten sam problem w naszym projekcie. Chciałem również dodać parametry nagłówka do witryny Swagger UI. Oto, jak to zrobiliśmy:

1.Definiowanie klasy OperationFilter Operacje Filtry są wykonywane przy każdej operacji API za każdym razem, gdy budujesz Swagger. Zgodnie z Twoim kodem operacje będą sprawdzane zgodnie z Twoimi filtrami. W tym przykładzie parametr nagłówka jest wymagany przy każdej operacji, ale opcjonalny dla operacji z atrybutem AllowAnonymous.

public class AddAuthorizationHeader : IOperationFilter 
{ 
    /// <summary> 
    /// Adds an authorization header to the given operation in Swagger. 
    /// </summary> 
    /// <param name="operation">The Swashbuckle operation.</param> 
    /// <param name="schemaRegistry">The Swashbuckle schema registry.</param> 
    /// <param name="apiDescription">The Swashbuckle api description.</param> 
    public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription) 
    { 
     if (operation == null) return; 

     if (operation.parameters == null) 
     { 
      operation.parameters = new List<Parameter>(); 
     } 

     var parameter = new Parameter 
     { 
      description = "The authorization token", 
      @in = "header", 
      name = "Authorization", 
      required = true, 
      type = "string" 
     }; 

     if (apiDescription.ActionDescriptor.GetCustomAttributes<AllowAnonymousAttribute>().Any()) 
     { 
      parameter.required = false; 
     } 

     operation.parameters.Add(parameter); 
    } 
} 

2. Tell Swagger aby skorzystać z tej OperationFilter W SwaggerConfig, wystarczy dodać, że filtr operacja powinna być stosowana w sposób następujący:

c.OperationFilter<AddAuthorizationHeader>(); 

Nadzieja to pomaga się!

Answer 2

Można to zrobić na różne sposoby, w zależności od tego, jak zbieramy nagłówek Authorization i czy kod ma obsłużyć wszystko, czy też chcemy, aby użytkownik mógł wprowadzić żądany nagłówek.

Kiedy po raz pierwszy wypróbowałem to, mogłem pokazać tekst nagłówka Authorization w obszarze pola parametru każdego punktu końcowego, gdzie użytkownik mógł wpisać nagłówek Authorization, ale nie było to, co chciałem.

W mojej sytuacji musiałem wysłać żądanie do punktu końcowego /token za pomocą pliku cookie użytkownika, aby uzyskać ważny token Authorization. Zrobiłem mieszankę rzeczy, aby to osiągnąć.

pierwsze w SwaggerConfig.cs I Odkomentowano c.BasicAuth() aby uzyskać podstawowe schematu uwierzytelniania do schematu API i ja również wstrzykiwany niestandardowej index.html stronę gdzie wstawiony żądania AJAX w celu chwycić Authorization tokena, za pomocą pliku cookie użytkownika (pokazany kod index.html poniżej):

public static void Register() { 

    System.Reflection.Assembly thisAssembly = typeof(SwaggerConfig).Assembly; 

    System.Web.Http.GlobalConfiguration.Configuration 
       .EnableSwagger(c => { 
        ... 

        c.BasicAuth("basic").Description("Bearer Token Authentication"); 

        ... 
       }) 
       .EnableSwaggerUi(c => { 
        ... 

        c.CustomAsset("index", thisAssembly, "YourNamespace.index.html"); 

        ... 
       }); 
} 

Udaj here aby pobrać swashbuckle index.html które będziemy dostosowywać do wstawienia Authorization nagłówek.

Poniżej po prostu wykonać połączenie AJAX do mojego /token końcowego z ważnego pliku cookie, uzyskać Authorization tokena, i dać go do puszyć korzystać z window.swaggerUi.api.clientAuthorizations.add():

usunąłem kilka rzeczy z AJAX zadzwoń, aby było prostsze i oczywiście Twoja implementacja będzie prawdopodobnie różna w zależności od tego, jak zbierzesz swój token Authorization, ale to daje ci pomysł. Jeśli masz jakieś konkretne problemy lub pytania, daj mi znać.

* Edycja: Nie zauważyłem, że rzeczywiście chcesz, aby użytkownik wpisał swój nagłówek Authorization. W takim przypadku jest to bardzo łatwe. Użyłem postu this. Po prostu stworzony następujące klasy do pracy:

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 = "Foo-Header", 
      @in = "header", 
      type = "string", 
      required = true 
     }); 
    } 
} 

Następnie dodaje klasę do mojego SwaggerConfig tak:

... 
c.OperationFilter<AddRequiredHeaderParameter>(); 
... 

Answer 3

Utwórz nowy filtr operacji, który implementuje IOperationFilter.

public class AuthorizationHeaderOperationFilter : IOperationFilter 
{ 
    /// <summary> 
    /// Adds an authorization header to the given operation in Swagger. 
    /// </summary> 
    /// <param name="operation">The Swashbuckle operation.</param> 
    /// <param name="context">The Swashbuckle operation filter context.</param> 
    public void Apply(Operation operation, OperationFilterContext context) 
    { 
     if (operation.Parameters == null) 
     { 
      operation.Parameters = new List<IParameter>(); 
     } 

     var authorizeAttributes = context.ApiDescription 
      .ControllerAttributes() 
      .Union(context.ApiDescription.ActionAttributes()) 
      .OfType<AuthorizeAttribute>(); 
     var allowAnonymousAttributes = context.ApiDescription.ActionAttributes().OfType<AllowAnonymousAttribute>(); 

     if (!authorizeAttributes.Any() && !allowAnonymousAttributes.Any()) 
     { 
      return; 
     } 

     var parameter = new NonBodyParameter 
     { 
      Name = "Authorization", 
      In = "header", 
      Description = "The bearer token", 
      Required = true, 
      Type = "string" 
     }; 

     operation.Parameters.Add(parameter); 
    } 
} 

Skonfiguruj usługę w swoim pliku Startup.cs.

 services.ConfigureSwaggerGen(options => 
     { 
      options.OperationFilter<AuthorizationHeaderOperationFilter>(); 
     });