" EHealthCareClinic.WebApi " );c.IncludeXmlComments(GetXmlC

标签：

当Web Api 2.0使用OAuth2授权时，如安在Swagger中添加Authorization请求头？

Swagger说明文档撑持手动挪用Api, 但是当Api使用OAuth2授权时，由于没有处所可以输入授权Token, 导致响应功效一直是401没有授权。

解决方案：

在Swagger配置文件中，添加对请求头中Authorization的设置。

1. 在Api项目中添加一个新类AddAuthorizationHeader并实现IOperationFilter接口

public class AddAuthorizationHeader : IOperationFilter { /// <summary> /// Adds an authorization header to the given operation in Swagger. /// </summary> /// <param>The Swashbuckle operation.</param> /// <param>The Swashbuckle schema registry.</param> /// <param>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 = "Token", @in = "header", name = "Authorization", required = true, type = "string" }; if (apiDescription.ActionDescriptor.GetCustomAttributes<AllowAnonymousAttribute>().Any()) { //如果Api要领是允许匿名要领，Token不是必填的 parameter.required = false; } operation.parameters.Add(parameter); } }

2. 在SwaggerConfig.cs中启用Authorization请求头。

public static void Register(HttpConfiguration config) { var thisAssembly = typeof(SwaggerConfig).Assembly; config.EnableSwagger(c => { c.OperationFilter<AddAuthorizationHeader>(); c.SingleApiVersion("v1", "EHealthCareClinic.WebApi"); c.IncludeXmlComments(GetXmlCommentsPath()); }) .EnableSwaggerUi(c => { }); }

3. 编译Api项目，从头打开Swagger说明文档， Parameters列表中就会呈现Authorization变量，录入正确的授权Token,  401未授权问题消掉。

当Web Api 2.0使用IHttpActionResult作为返回值时，，如安在Swagger中生成Response Class典型？

IHttpActionResult是Web Api 2.0引入的接口。

使用IHttpActionResult作为Api  返回值的好处。

简化对控制器的单元测试

创建Http响应的通用逻辑被移动到单独的类中

通过隐藏构建相应的底层细节，使控制器行动更清晰

Swagger生成文档的道理是通过读取Web Api项目生成的XML文档说明文件，使用反射技术，动态展示每个Action要领的要领签名。

但是当使用IHttpActionResult作为Api要领返回值之后，Swagger不能通过反射正确读取到返回值的类型，所以导致生成的文档缺少。

例：

/// <summary> /// 获取省份列表 /// <param>国家ID</param> /// </summary> [HttpGet] [Route("countries/{countryId}/provinces")] public IHttpActionResult GetProvinceList(Guid countryId) { var result = QueryService.GetProvinceCollection(new CountryId(countryId)); return Ok(result); }

  解决方案:

Web Api 2.0中引入了一个新的特性类System.Web.Http.Description.ResponseTypeAttribute。

这个特性类结构只有一个参数，即返回值的类型。

我们只需要在每个Api要领签名处使用这个新特性声明Api返回值的类型, Swagger生成的说明文档中就会呈现返回类型的说明。