[英]How do I include subclasses in Swagger API documentation/ OpenAPI specification using Swashbuckle?
[英]How do I add header documentation in Swashbuckle?
我正在使用图书馆Swashbuckle。 当前没有针对它的stackoverflow标签。
我对此处的文档不太了解: https : //github.com/domaindrivendev/Swashbuckle/blob/master/README.md
标题为“描述安全性/授权方案”的部分提到了一段代码
c.ApiKey("apiKey")
.Description("API Key Authentication")
.Name("apiKey")
.In("header");
但是,当我将其包括在内时,什么也不会发生。 我也希望仅出现在某些API方法上。 它确实提到
“需要与文档上的相应“安全”属性相结合”
但是我不明白。
谁能解释?
我有同样的问题,并以此方式解决:
在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);
}
}
然后,swagger文件具有安全性定义:
"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"
}
]
Swashbuckle维护者建议我们提供一个自定义index.html来执行此操作,因为他将在下一个主要版本中删除这些配置。 看到这个问题 。
提供您自己的“索引”文件
使用CustomAsset选项指示Swashbuckle在请求“索引”时返回您的版本而不是默认版本。 与所有自定义内容一样,该文件必须作为“嵌入式资源”包含在您的项目中,然后将资源的“逻辑名”传递给方法,如下所示。 有关分步说明,请参阅注入自定义内容 。
为了兼容,您应该基于此版本自定义“ index.html”。
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);
}
}
config.EnableSwagger(c =>
{
c.SingleApiVersion("v1", "TestApiWithToken");
c.ApiKey("Token")
.Description("Filling bearer token here")
.Name("Authorization")
.In("header");
})
.EnableSwaggerUi(c =>
{
c.EnableApiKeySupport("Authorization", "header");
});
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.