Jak dodać dokumentację nagłówka w Swashbuckle?

Question

Używam biblioteki Swashbuckle. Obecnie nie ma dla niego tagu stackoverflow.

ja nie bardzo rozumiem dokumentację tutaj: https://github.com/domaindrivendev/Swashbuckle/blob/master/README.md

w sekcji „Opisywanie zabezpieczeń Schematy/zezwolenie” wspomina o kawałek kodu

c.ApiKey("apiKey") 
       .Description("API Key Authentication") 
       .Name("apiKey") 
       .In("header"); 

Jednak kiedy to to nic się nie dzieje. Chciałbym również, aby pojawiało się tylko w niektórych metodach API. To nie wspominając

„muszą być połączone z odpowiednim«ochrony»własności w dokumencie ”

Ale ja tego nie rozumiem.

Czy ktoś może wyjaśnić?

Answer 1

Miałem to samo pytanie i rozwiązać to w ten sposób:

At SwaggerConfig:

var applyApiKeySecurity = new ApplyApiKeySecurity(
    key: "ServiceBusToken", 
    name: "Authorization", 
    description: "Service Bus Token, e.g. 'SharedAccessSignature sr=...&sig=...&se=...&skn=...'", 
    @in: "header" 
); 
applyApiKeySecurity.Apply(c); 

ApplyApiKeySecurity:

public class ApplyApiKeySecurity : IDocumentFilter, IOperationFilter 
{ 
    public ApplyApiKeySecurity(string key, string name, string description, string @in) 
    { 
     Key = key; 
     Name = name; 
     Description = description; 
     In = @in; 
    } 

    public string Description { get; private set; } 

    public string In { get; private set; } 

    public string Key { get; private set; } 

    public string Name { get; private set; } 

    public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, System.Web.Http.Description.IApiExplorer apiExplorer) 
    { 
     IList<IDictionary<string, IEnumerable<string>>> security = new List<IDictionary<string, IEnumerable<string>>>(); 
     security.Add(new Dictionary<string, IEnumerable<string>> { 
      {Key, new string[0]} 
     }); 

     swaggerDoc.security = security; 
    } 

    public void Apply(Operation operation, SchemaRegistry schemaRegistry, System.Web.Http.Description.ApiDescription apiDescription) 
    { 
     operation.parameters = operation.parameters ?? new List<Parameter>(); 
     operation.parameters.Add(new Parameter 
     { 
      name = Name, 
      description = Description, 
      @in = In, 
      required = true, 
      type = "string" 
     }); 
    } 

    public void Apply(Swashbuckle.Application.SwaggerDocsConfig c) 
    { 
     c.ApiKey(Key) 
      .Name(Name) 
      .Description(Description) 
      .In(In); 
     c.DocumentFilter(() => this); 
     c.OperationFilter(() => this); 
    } 
} 

Następnie plik Swagger ma Definition zabezpieczeń:

"securityDefinitions":{ 
    "ServiceBusToken":{ 
    "type":"apiKey", 
    "description":"Service Bus Token, e.g. 'SharedAccessSignature sr=...&sig=...&se=...&skn=...'", 
    "name":"Authorization", 
    "in":"header" 
    } 
} 

Stosowany do wszystkich operacji na poziomie dokumentu:

"security":[ 
    { 
    "ServiceBusToken":[] 
    } 
] 

a wszystkie operacje mają przypisany parametr nagłówka:

"parameters":[ 
    { 
     "name":"Authorization", 
     "in":"header", 
     "description":"Service Bus Token, e.g. 'SharedAccessSignature sr=...&sig=...&se=...&skn=...'", 
     "required":true, 
     "type":"string" 
    } 
] 

Answer 2

Swashbuckle opiekun zaleca nam dostarczać niestandardową index.html, aby to zrobić, ponieważ będzie on usunąć te konfiguracje w następnej wersji głównej. Zobacz tę issue.

dostarczyć własne „index” plik

Użyj opcję CustomAsset pouczać Swashbuckle wrócić wersję zamiast domyślnego, gdy wniosek został złożony dla „indeks”. Podobnie jak w przypadku wszystkich niestandardowych treści, plik musi być zawarty w projekcie jako "Osadzony zasób", a następnie "Nazwa logiczna" zasobu jest przekazywana do metody, jak pokazano poniżej. Instrukcje dotyczące krok po kroku można znaleźć na stronie Injecting Custom Content.

W celu zapewnienia zgodności należy oprzeć niestandardowy "index.html" na this version.

httpConfiguration 
    .EnableSwagger(c => c.SingleApiVersion("v1", "A title for your API")) 
    .EnableSwaggerUi(c => 
     { 
      c.CustomAsset("index", yourAssembly, "YourWebApiProject.SwaggerExtensions.index.html"); 
     }); 

W index.html będziesz chciał zmienić metodę poniżej, aby coś takiego:

function addApiKeyAuthorization(){ 
    var key = encodeURIComponent($('#input_apiKey')[0].value); 
    if(key && key.trim() != "") { 
     var apiKeyAuth = new SwaggerClient.ApiKeyAuthorization("sessionId", key, "header"); 
     window.swaggerUi.api.clientAuthorizations.add("sessionId", apiKeyAuth); 
     log("added key " + key); 
    } 
}