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

Posted 2020-10-16

 

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