系列导航及源代码

需求

在日常开发中,我们需要给前端提供文档化的API接口定义,甚至需要模拟架设一个fake服务用来调试接口字段。或者对于后端开发人员来说,我们可以通过导入这个接口定义文件到Postman或者其他API客户端,省去我们手动录入的麻烦。所以本文就实现如何使用Swagger来管理API接口文档化。

但是在本文中,我们不涉及关于NSwag的相关内容,通过NSwag,我们甚至可以直接生成前端可以使用的接口定义。关于NSwag的使用方法,请参考:NSwag 和 ASP.NET Core 入门以及官方文档RicoSuter/NSwag

目标

实现TodoList项目的接口文档化。

原理与思路

在使用IDE或者cli生成新的Web API项目的时候,项目模版里已经自带了Swashbuckle.AspNetCore包用来生成swagger文档,我们需要使用这个包来实现相关功能。

实现

实现基础的Swagger API文档

Program中极有可能已经添加了SwaggerGen服务了,我们可以做一点小修改,因为之前我们写过两个版本的TodoItemController,希望将两个版本也反映到swagger文档中:

  1. // 省略其他...
  2. builder.Services.AddSwaggerGen(s =>
  3. {
  4. s.SwaggerDoc("1.0", new OpenApiInfo { Title = "TodoList API", Version = "1.0"});
  5. s.SwaggerDoc("2.0", new OpenApiInfo { Title = "TodoList API", Version = "2.0"});
  6. });

中间件的引入我们也可以修改一下:

  1. if (app.Environment.IsDevelopment())
  2. {
  3. app.UseSwagger();
  4. app.UseSwaggerUI(s =>
  5. {
  6. s.SwaggerEndpoint("/swagger/1.0/swagger.json", "TodoList API v1.0");
  7. s.SwaggerEndpoint("/swagger/2.0/swagger.json", "TodoList API v2.0");
  8. });
  9. }

如果在API接口版本控制的那一章我们不是使用的通过更改URL的方式实现的API多版本,那么现在只需要对应版本的Controller上添加:

  • TodoItemController.cs
  1. [Route("/todo-item")]
  2. [ApiExplorerSettings(GroupName = "1.0")]
  3. [ApiController]
  4. public class TodoItemController : ControllerBase
  5. // 省略其他...

以及

  • TodoItemV2Controller.cs
  1. [Route("/todo-item")]
  2. [ApiExplorerSettings(GroupName = "2.0")]
  3. [ApiController]
  4. public class TodoItemV2Controller : ControllerBase
  5. // 省略其他...

如果是使用URL路径实现不同版本API的文档,可以参考这篇文章的实现:ASP.NET Core 3.1 WebApi Swagger与API版本控制的美妙结合

为Swagger添加认证授权功能

为了添加授权支持,我们可以修改Swagger服务选项如下,增加授权配置:

  • Program.cs
  1. // 省略其他
  2. s.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
  3. {
  4. In = ParameterLocation.Header,
  5. Description = "Add JWT with Bearer",
  6. Name = "Authorization",
  7. Type = SecuritySchemeType.ApiKey,
  8. Scheme = "Bearer"
  9. });
  10. s.AddSecurityRequirement(new OpenApiSecurityRequirement
  11. {
  12. {
  13. new OpenApiSecurityScheme
  14. {
  15. Reference = new OpenApiReference
  16. {
  17. Type = ReferenceType.SecurityScheme,
  18. Id = "Bearer"
  19. },
  20. Name = "Bearer",
  21. },
  22. new List<string>()
  23. }
  24. });

验证

启动Api项目,打开swagger地址,可以看到API版本选择,以及授权控制都在界面上有所显示。

具体的切换查看我就不贴截图了,大家可以自己试一试。

一点扩展

导入API客户端

右击swagger界面上的json文件链接选择另存为,再去对应的API客户端导入json文件即可。

Postman在这方面做的比较好的是它能够按照json文件内接口的结构关系生成对应的文件夹结构。

生成fake服务端

可以去这里:Swagger Editor,上传swagger json文件,选择生成服务端或者客户端。

为swagger生成完整的数据定义及API注释文档

需要开启XML注释功能,为此我们同时需要禁止1591warning(为了避免对所有的方法、类、字段发出没有xml注释文档的警告)。修改项目设置如下:

  1. <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
  2. <DocumentationFile>TodoList.Api.xml</DocumentationFile>
  3. <OutputPath></OutputPath>
  4. <NoWarn>1701;1702;1591</NoWarn>
  5. </PropertyGroup>
  6. <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
  7. <NoWarn>1701;1702;1591</NoWarn>
  8. </PropertyGroup>

修改SwaggerGen注入的配置:

  • TodoList.Api.csproj
  1. var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
  2. var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
  3. s.IncludeXmlComments(xmlPath);

我们以CreateTodoList接口为例去添加xml注释,

  • TodoListController.cs
  1. /// <summary>
  2. /// 创建新的TodoList,只有Administrator角色的用户有此权限
  3. /// </summary>
  4. /// <param name="command">创建TodoList命令</param>
  5. /// <returns></returns>
  6. [HttpPost]
  7. [Authorize(Policy = "OnlyAdmin")]
  8. [ServiceFilter(typeof(LogFilterAttribute))]
  9. public async Task<ApiResponse<Domain.Entities.TodoList>> Create([FromBody] CreateTodoListCommand command)
  10. {
  11. return ApiResponse<Domain.Entities.TodoList>.Success(await _mediator.Send(command));
  12. }

再打开swagger文档查看,可以看到swagger文档现在已经有接口说明了:

总结

在本文中我们实现了swagger文档的生成和一些配置选项的作用,如果需要用到更多OpenAPI相关的特性,推荐熟悉一下NSwag这个组件,它提供了更加强大的功能。

下一篇文章我们实现程序的健康检查功能。

参考资料

  1. NSwag 和 ASP.NET Core 入门
  2. RicoSuter/NSwag
  3. ASP.NET Core 3.1 WebApi Swagger与API版本控制的美妙结合

使用.NET 6开发TodoList应用(27)——实现API的Swagger文档化的更多相关文章

  1. 通过Swagger文档生成前端service文件,提升前端开发效率

    在企业级的项目开发过程中,一般会采用前后端分离的开发方式,前后端通过api接口进行通信,所以接口文档就显得十分的重要. 目前大多数的公司都会引入Swagger来自动生成文档,大大提高了前后端分离开发的 ...

  2. 使用.NET 6开发TodoList应用(21)——实现API版本控制

    系列导航及源代码 使用.NET 6开发TodoList应用文章索引 需求 API接口版本管理,对于一些规模稍大的企业应用来说,是经常需要关注的一大需求.尽管我们的示例程序TodoList很简单,但是我 ...

  3. MFC开发上位机到底用Dialog结构还是文档结构?

    最近要跟着导师一起开发一款大型上位机.MFC新人在考虑用对话框结构还是文档结构. 虽然说书上说大型结构的软件都需要文档结构,但是目前来看,对话框可以实现功能,并且对话框的程序更小一些,节省资源加载速度 ...

  4. 使用Word API打开Word文档 ASP.NET编程中常用到的27个函数集

    使用Word API(非Openxml)打开Word文档简单示例(必须安装Word) 首先需要引入参照Microsoft.Office.Interop.Word 代码示例如下: public void ...

  5. iTOP-4412开发板-串口转接小板的使用文档

    本文档介绍如何使用 迅为iTOP-4412 精英版如何使用串口转接板,串口小板如下所示.和串口转接板模块相关的资料如下:“iTOP-4412-Android-串口测试文档(升级版)_V2.X.zip” ...

  6. Spring 5 中函数式web开发中的swagger文档

    Spring 5 中一个非常重要的更新就是增加了响应式web开发WebFlux,并且推荐使用函数式风格(RouterFunction和 HandlerFunction)来开发WebFlux.对于之前主 ...

  7. Python开发技术详解(视频+源码+文档)

    Python, 是一种面向对象.直译式计算机程序设计语言.Python语法简捷而清晰,具有丰富和强大的类库.它常被昵称为胶水语言,它能够很轻松的把用其他语言制作的各种模块(尤其是C/C++)轻松地联结 ...

  8. 【Qt开发】QThread 实用技巧、误区----但文档中没有提到

    本文主要内容: 在任务一中,用 四 种方式实现:点击界面按钮,开线程运行一段程序,结果显示在一个Label上.1. 用不正确的方式得到看似正确的结果2. 用Qt Manual 和 例子中使用的方法3. ...

  9. itop4412开发版-安卓系统卸载默认apk使用文档

    itop4412开发版的安卓系统默认不是最高权限,可以看见后面最后一个是$符号,如下图 1,所以 想我们需要进入 root 权限,可以看见后面最后一个是#符号,如下图所示.在这个变换中只需 要在超级终 ...

随机推荐

  1. de1ctf_2019_weapon(爆破_IO_2_1_stdout)

    (这是我真正意义上的完完全全自己做的第一道堆题目,虽然花了快三个小时,谨以此篇纪念一下) 题目的例行检查我就不放了,将程序放入ida中 程序的逻辑十分简单,漏洞也非常明显 重点是这个程序没有给我们sh ...

  2. 一道栈溢出babystack

    我太天真了,师傅说让我做做这个平台的题,我就注册了个号,信心满满的打开了change,找到了pwn,一看第一道题是babystack,我想着,嗯,十分钟搞定他!直到我下载了题目,题目给了libc,然后 ...

  3. SpringCloud微服务实战——搭建企业级开发框架(三十四):SpringCloud + Docker + k8s实现微服务集群打包部署-Maven打包配置

      SpringCloud微服务包含多个SpringBoot可运行的应用程序,在单应用程序下,版本发布时的打包部署还相对简单,当有多个应用程序的微服务发布部署时,原先的单应用程序部署方式就会显得复杂且 ...

  4. CF1560D Make a Power of Two 题解

    Content 给定一个整数 \(n\).每次操作你可以做两件事情中的一件: 删去这个数中的一个数位(如果这个数只剩下一位,则可以把它删空). 在这个数的右边添加一个数位. 你可以以任意顺序执行无限次 ...

  5. nim_duilib(1)之第一个dui executable(including configure setting in vs2017)

    before starting clone nim_duilib: https://github.com/netease-im/NIM_Duilib_Framework 迁出github的源码即可. ...

  6. 【LeetCode】84. Largest Rectangle in Histogram 柱状图中最大的矩形(Python)

    作者: 负雪明烛 id: fuxuemingzhu 个人博客: http://fuxuemingzhu.cn/ 目录 题目描述 题目大意 解题方法 单调栈 日期 题目地址: https://leetc ...

  7. Codeforces 777D:Cloud of Hashtags(暴力,水题)

    Vasya is an administrator of a public page of organization "Mouse and keyboard" and his ev ...

  8. [Elasticsearch] ES聚合场景下部分结果数据未返回问题分析

    背景 在对ES某个筛选字段聚合查询,类似groupBy操作后,发现该字段新增的数据,聚合结果没有展示出来,但是用户在全文检索新增的筛选数据后,又可以查询出来, 针对该问题进行了相关排查. 排查思路 首 ...

  9. Boost的反射库PFR

    目录 目录 简介 使用方法 限制 总结 简介 Boost.PFR是一个Boost 1.75版本出的C++14的基础反射库,其使用非常简单,非常便捷,但是适用性也比较差,有很多的地方无法使用,适合比较简 ...

  10. 第七个知识点:随机性如何辅助计算和什么是BPP类问题

    第七个知识点:随机性如何辅助计算和什么是BPP类问题 原文地址:http://bristolcrypto.blogspot.com/2014/11/52-things-number-7-how-doe ...