Web Api 2.0中使用Swagger生成Api文档的2个小Tips

当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 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 = "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 name="countryId">国家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生成的说明文档中就会出现返回类型的说明。

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