标签：health 项目 schema cli 响应 参数 clu alt list
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未授权问题消失。
IHttpActionResult是Web Api 2.0引入的接口。
使用IHttpActionResult作为Api 返回值的好处。
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); }
Web Api 2.0中使用Swagger生成Api文档的2个小Tips
标签：health 项目 schema cli 响应 参数 clu alt list
原文地址：http://www.cnblogs.com/lwqlun/p/7998523.html
