Как добавить заголовочную документацию в Swashbuckle?

Question

Я использую библиотеку Swashbuckle. В настоящее время для него нет тега stackoverflow.

Я не совсем понимаю документацию здесь: https://github.com/domaindrivendev/Swashbuckle/blob/master/README.md

раздел под названием «Описание безопасности/авторизации Схемы» упоминает фрагмент кода

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

Однако, когда я включаю это ничего не происходит. Мне также хотелось бы, чтобы это отображалось только по некоторым API-методам. Он упоминает

«должен быть соединен с соответствующей„безопасностью“собственностью на документе»

Но я не понимаю этого.

Может ли кто-нибудь объяснить?

Answer 1

У меня был тот же вопрос, и решить его таким образом:

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

Затем файл чванство имеет Definiton безопасности:

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

Применительно ко всем операциям на уровне документа:

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

И все операции имеют параметр заголовка назначенный:

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

Answer 2

Swashbuckle Сопровождающие рекомендует нам предоставлять пользовательский index.html, чтобы сделать это, потому что он будет удалить эти конфигурации в следующей крупной версии. См. Это issue.

Обеспечить свой собственный «индекс» файл

Используйте вариант CustomAsset поручить Swashbuckle, чтобы вернуть версию вместо значения по умолчанию, если запрос сделан для «индекса». Как и во всем настраиваемом контенте, файл должен быть включен в ваш проект как «Встроенный ресурс», а затем «Логическое имя» ресурса передается методу, как показано ниже. См. Injecting Custom Content для пошаговых инструкций.

Для обеспечения совместимости вы должны создать свой собственный «index.html» с this version.

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

В index.html вы хотите изменить метод ниже, чтобы что-то вроде этого:

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