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

2021-04-23 05:26

阅读：767

标签：health 项目 schema cli 响应参数 clu alt list

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

Swagger说明文档支持手动调用Api, 但是当Api使用OAuth2授权时，由于没有地方可以输入授权Token, 导致响应结果一直是401没有授权。

技术分享图片

解决方案：

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

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

    public class AddAuthorizationHeader : IOperationFilter
    {
        /// 
        /// Adds an authorization header to the given operation in Swagger.
        /// 
        /// The Swashbuckle operation.
        /// The Swashbuckle schema registry.
        /// The Swashbuckle api description.
        public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
        {
            if (operation == null) return;

            if (operation.parameters == null)
            {
                operation.parameters = new List();

            }


            var parameter = new Parameter
            {
                description = "Token",
                @in = "header",
                name = "Authorization",
                required = true,
                type = "string"
            };


            if (apiDescription.ActionDescriptor.GetCustomAttributes().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();

                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不能通过反射正确读取到返回值的类型，所以导致生成的文档缺少。

例：

        /// 
        /// 获取省份列表
        /// 国家ID
        /// 
        [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生成的说明文档中就会出现返回类型的说明。

        /// 
        /// 获取省份列表
        /// 国家ID
        /// 
        [HttpGet]
        [Route("countries/{countryId}/provinces")]
        [ResponseType(typeof(IEnumerable))]
        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

上一篇：AudioEffect中文API

下一篇：[TC_SRM_466]Drawing Black Crosses

文章来自：搜素材网的编程语言模块，转载请注明文章出处。
文章标题：Web Api 2.0中使用Swagger生成Api文档的2个小Tips
文章链接：http://soscw.com/essay/78400.html

亲，登录后才可以留言！

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

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

解决方案：

当Web Api 2.0使用IHttpActionResult作为返回值时，如何在Swagger中生成Response Class范例？

解决方案:

评论

热门文章

推荐文章

最新文章

置顶文章