当前位置:首页 > 服务端 > Web Api 2.0中使用Swagger生成Api文档的2个小Tips

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

2022年08月06日 08:40:50服务端6

 

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

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

 

Web Api 2.0中使用Swagger生成Api文档的2个小Tips _ JavaClub全栈架构师技术笔记

 

解决方案:

在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中使用Swagger生成Api文档的2个小Tips _ JavaClub全栈架构师技术笔记

 

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

IHttpActionResult是Web Api 2.0引入的接口。

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

  • 简化对控制器的单元测试
  • 创建Http响应的通用逻辑被移动到单独的类中
  • 通过隐藏构建相应的底层细节,使控制器动作更清晰

 

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

 Web Api 2.0中使用Swagger生成Api文档的2个小Tips _ JavaClub全栈架构师技术笔记

但是当使用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中使用Swagger生成Api文档的2个小Tips _ JavaClub全栈架构师技术笔记 

解决方案:

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 _ JavaClub全栈架构师技术笔记

 

作者:LamondLu
来源链接:https://www.cnblogs.com/lwqlun/p/7998523.html

版权声明:
1、JavaClub(https://www.javaclub.cn)以学习交流为目的,由作者投稿、网友推荐和小编整理收藏优秀的IT技术及相关内容,包括但不限于文字、图片、音频、视频、软件、程序等,其均来自互联网,本站不享有版权,版权归原作者所有。

2、本站提供的内容仅用于个人学习、研究或欣赏,以及其他非商业性或非盈利性用途,但同时应遵守著作权法及其他相关法律的规定,不得侵犯相关权利人及本网站的合法权利。
3、本网站内容原作者如不愿意在本网站刊登内容,请及时通知本站(javaclubcn@163.com),我们将第一时间核实后及时予以删除。


本文链接:https://www.javaclub.cn/server/18294.html

标签: Swagger
分享给朋友:

“Web Api 2.0中使用Swagger生成Api文档的2个小Tips” 的相关文章

IDEA技巧:如何根据注释生成swagger注解

IDEA技巧:如何根据注释生成swagger注解

相信大家在进行java项目开发,肯定会接触到swagger的,一款动态生成api文档的神奇,只需要在api上面加上注解,就可以生成文档,现在我简单介绍下swagger的快速入门,最后再说下如何根据注释快速生成这些烦人的注解。 ​ swagger日常...

SpringBoot整合Swagger和Actuator

SpringBoot整合Swagger和Actuator

前言 本篇文章主要介绍的是SpringBoot整合Swagger(API文档生成框架)和SpringBoot整合Actuator(项目监控)使用教程。 SpringBoot整合Swagger 说明:如果想直接获取工程那么可以直接跳到底部,通过链接下载工程代码。...

SpringBoot整合Swagger2

SpringBoot整合Swagger2

相信各位在公司写API文档数量应该不少,当然如果你还处在自己一个人开发前后台的年代,当我没说,如今为了前后台更好的对接,还是为了以后交接方便,都有要求写API文档。   手写Api文档的几个痛点: 文档需要更新的时候,需要再次发送...

使用dropwizard(5)--加入swagger

使用dropwizard(5)--加入swagger

前言 Swagger已经成API service的规范了,本处在dropwizard中简单集成Swagger. Demo source https://github.com/Ryan-Miao/l4dropwizard 本文是基于dropwizard入...

Visual Studio 2017 and Swagger: Building and Documenting Web APIs

Visual Studio 2017 and Swagger: Building and Documenting Web APIs

Swagger是一种与技术无关的标准,允许发现REST API,为任何软件提供了一种识别REST API功能的方法。 这比看起来更重要:这是一个改变游戏技术的方式,就像Web服务描述语言一样WSDL(Web Service Description Language)一样。...

使用Swagger直接上传文件的方法

使用Swagger直接上传文件的方法

经常使用swagger,可以通过设置[ProducesResponseType]标记接口的返回信息;swagger也能通过接口的参数列表,自动获得发送的数据结构信息。 不过有一个例外,就是上传文件的时候,设置了[Consumes]的内容为multi-part/form-data,...

从壹开始前后端分离【 .NET Core2.2/3.0 +Vue2.0 】框架之五 || Swagger的使用 3.3 JWT权限验证【必看】

从壹开始前后端分离【 .NET Core2.2/3.0 +Vue2.0 】框架之五 || Swagger的使用 3.3 JWT权限验证【必看】

本文3.0版本文章 https://mp.weixin.qq.com/s/7135y3MkUlPIp-flfwscig   下边的是我关于JWT的视频讲解,都可以看看 1、P2直播12期:授权与认证(1)_简单授权 2、P3直播13期:授权与认...

Swagger使用

Swagger使用

原文:https://www.cnblogs.com/liruiloveparents/p/9378327.html     Swagger学习及生成HTML文档 Swagger 1、集成springboot 第一步:pom...

swagger整合springboot的使用

swagger整合springboot的使用

什么是swagger? Swagger 是一个规范且完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口,可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服...

Asp.Net WebApi swagger使用教程

Asp.Net WebApi swagger使用教程

swagger简介 别名:丝袜哥 功能:用于生产api文档 swagger安装 Nuget搜索swagger,然后安装Swashbuckle swagger使用 生成api的xml文档 webapi项目右键——属性——生产——输出...

发表评论

访客

◎欢迎参与讨论,请在这里发表您的看法和观点。