使用.NET 6开发TodoList应用(27)——实现API的Swagger文档化
系列导航及源代码
需求
在日常开发中,我们需要给前端提供文档化的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文档中:
// 省略其他...
builder.Services.AddSwaggerGen(s =>
{
s.SwaggerDoc("1.0", new OpenApiInfo { Title = "TodoList API", Version = "1.0"});
s.SwaggerDoc("2.0", new OpenApiInfo { Title = "TodoList API", Version = "2.0"});
});
中间件的引入我们也可以修改一下:
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI(s =>
{
s.SwaggerEndpoint("/swagger/1.0/swagger.json", "TodoList API v1.0");
s.SwaggerEndpoint("/swagger/2.0/swagger.json", "TodoList API v2.0");
});
}
如果在API接口版本控制的那一章我们不是使用的通过更改URL的方式实现的API多版本,那么现在只需要对应版本的Controller上添加:
TodoItemController.cs
[Route("/todo-item")]
[ApiExplorerSettings(GroupName = "1.0")]
[ApiController]
public class TodoItemController : ControllerBase
// 省略其他...
以及
TodoItemV2Controller.cs
[Route("/todo-item")]
[ApiExplorerSettings(GroupName = "2.0")]
[ApiController]
public class TodoItemV2Controller : ControllerBase
// 省略其他...
如果是使用URL路径实现不同版本API的文档,可以参考这篇文章的实现:ASP.NET Core 3.1 WebApi Swagger与API版本控制的美妙结合
为Swagger添加认证授权功能
为了添加授权支持,我们可以修改Swagger服务选项如下,增加授权配置:
Program.cs
// 省略其他
s.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
In = ParameterLocation.Header,
Description = "Add JWT with Bearer",
Name = "Authorization",
Type = SecuritySchemeType.ApiKey,
Scheme = "Bearer"
});
s.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference
{
Type = ReferenceType.SecurityScheme,
Id = "Bearer"
},
Name = "Bearer",
},
new List<string>()
}
});
验证
启动Api
项目,打开swagger地址,可以看到API版本选择,以及授权控制都在界面上有所显示。
具体的切换查看我就不贴截图了,大家可以自己试一试。
一点扩展
导入API客户端
右击swagger界面上的json文件链接选择另存为,再去对应的API客户端导入json文件即可。
Postman在这方面做的比较好的是它能够按照json文件内接口的结构关系生成对应的文件夹结构。
生成fake服务端
可以去这里:Swagger Editor,上传swagger json文件,选择生成服务端或者客户端。
为swagger生成完整的数据定义及API注释文档
需要开启XML注释功能,为此我们同时需要禁止1591warning(为了避免对所有的方法、类、字段发出没有xml注释文档的警告)。修改项目设置如下:
<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
<DocumentationFile>TodoList.Api.xml</DocumentationFile>
<OutputPath></OutputPath>
<NoWarn>1701;1702;1591</NoWarn>
</PropertyGroup>
<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
<NoWarn>1701;1702;1591</NoWarn>
</PropertyGroup>
修改SwaggerGen注入的配置:
TodoList.Api.csproj
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
s.IncludeXmlComments(xmlPath);
我们以CreateTodoList
接口为例去添加xml注释,
TodoListController.cs
/// <summary>
/// 创建新的TodoList,只有Administrator角色的用户有此权限
/// </summary>
/// <param name="command">创建TodoList命令</param>
/// <returns></returns>
[HttpPost]
[Authorize(Policy = "OnlyAdmin")]
[ServiceFilter(typeof(LogFilterAttribute))]
public async Task<ApiResponse<Domain.Entities.TodoList>> Create([FromBody] CreateTodoListCommand command)
{
return ApiResponse<Domain.Entities.TodoList>.Success(await _mediator.Send(command));
}
再打开swagger文档查看,可以看到swagger文档现在已经有接口说明了:
总结
在本文中我们实现了swagger文档的生成和一些配置选项的作用,如果需要用到更多OpenAPI相关的特性,推荐熟悉一下NSwag这个组件,它提供了更加强大的功能。
下一篇文章我们实现程序的健康检查功能。
参考资料
使用.NET 6开发TodoList应用(27)——实现API的Swagger文档化的更多相关文章
- 通过Swagger文档生成前端service文件,提升前端开发效率
在企业级的项目开发过程中,一般会采用前后端分离的开发方式,前后端通过api接口进行通信,所以接口文档就显得十分的重要. 目前大多数的公司都会引入Swagger来自动生成文档,大大提高了前后端分离开发的 ...
- 使用.NET 6开发TodoList应用(21)——实现API版本控制
系列导航及源代码 使用.NET 6开发TodoList应用文章索引 需求 API接口版本管理,对于一些规模稍大的企业应用来说,是经常需要关注的一大需求.尽管我们的示例程序TodoList很简单,但是我 ...
- MFC开发上位机到底用Dialog结构还是文档结构?
最近要跟着导师一起开发一款大型上位机.MFC新人在考虑用对话框结构还是文档结构. 虽然说书上说大型结构的软件都需要文档结构,但是目前来看,对话框可以实现功能,并且对话框的程序更小一些,节省资源加载速度 ...
- 使用Word API打开Word文档 ASP.NET编程中常用到的27个函数集
使用Word API(非Openxml)打开Word文档简单示例(必须安装Word) 首先需要引入参照Microsoft.Office.Interop.Word 代码示例如下: public void ...
- iTOP-4412开发板-串口转接小板的使用文档
本文档介绍如何使用 迅为iTOP-4412 精英版如何使用串口转接板,串口小板如下所示.和串口转接板模块相关的资料如下:“iTOP-4412-Android-串口测试文档(升级版)_V2.X.zip” ...
- Spring 5 中函数式web开发中的swagger文档
Spring 5 中一个非常重要的更新就是增加了响应式web开发WebFlux,并且推荐使用函数式风格(RouterFunction和 HandlerFunction)来开发WebFlux.对于之前主 ...
- Python开发技术详解(视频+源码+文档)
Python, 是一种面向对象.直译式计算机程序设计语言.Python语法简捷而清晰,具有丰富和强大的类库.它常被昵称为胶水语言,它能够很轻松的把用其他语言制作的各种模块(尤其是C/C++)轻松地联结 ...
- 【Qt开发】QThread 实用技巧、误区----但文档中没有提到
本文主要内容: 在任务一中,用 四 种方式实现:点击界面按钮,开线程运行一段程序,结果显示在一个Label上.1. 用不正确的方式得到看似正确的结果2. 用Qt Manual 和 例子中使用的方法3. ...
- itop4412开发版-安卓系统卸载默认apk使用文档
itop4412开发版的安卓系统默认不是最高权限,可以看见后面最后一个是$符号,如下图 1,所以 想我们需要进入 root 权限,可以看见后面最后一个是#符号,如下图所示.在这个变换中只需 要在超级终 ...
随机推荐
- de1ctf_2019_weapon(爆破_IO_2_1_stdout)
(这是我真正意义上的完完全全自己做的第一道堆题目,虽然花了快三个小时,谨以此篇纪念一下) 题目的例行检查我就不放了,将程序放入ida中 程序的逻辑十分简单,漏洞也非常明显 重点是这个程序没有给我们sh ...
- 一道栈溢出babystack
我太天真了,师傅说让我做做这个平台的题,我就注册了个号,信心满满的打开了change,找到了pwn,一看第一道题是babystack,我想着,嗯,十分钟搞定他!直到我下载了题目,题目给了libc,然后 ...
- SpringCloud微服务实战——搭建企业级开发框架(三十四):SpringCloud + Docker + k8s实现微服务集群打包部署-Maven打包配置
SpringCloud微服务包含多个SpringBoot可运行的应用程序,在单应用程序下,版本发布时的打包部署还相对简单,当有多个应用程序的微服务发布部署时,原先的单应用程序部署方式就会显得复杂且 ...
- CF1560D Make a Power of Two 题解
Content 给定一个整数 \(n\).每次操作你可以做两件事情中的一件: 删去这个数中的一个数位(如果这个数只剩下一位,则可以把它删空). 在这个数的右边添加一个数位. 你可以以任意顺序执行无限次 ...
- nim_duilib(1)之第一个dui executable(including configure setting in vs2017)
before starting clone nim_duilib: https://github.com/netease-im/NIM_Duilib_Framework 迁出github的源码即可. ...
- 【LeetCode】84. Largest Rectangle in Histogram 柱状图中最大的矩形(Python)
作者: 负雪明烛 id: fuxuemingzhu 个人博客: http://fuxuemingzhu.cn/ 目录 题目描述 题目大意 解题方法 单调栈 日期 题目地址: https://leetc ...
- Codeforces 777D:Cloud of Hashtags(暴力,水题)
Vasya is an administrator of a public page of organization "Mouse and keyboard" and his ev ...
- [Elasticsearch] ES聚合场景下部分结果数据未返回问题分析
背景 在对ES某个筛选字段聚合查询,类似groupBy操作后,发现该字段新增的数据,聚合结果没有展示出来,但是用户在全文检索新增的筛选数据后,又可以查询出来, 针对该问题进行了相关排查. 排查思路 首 ...
- Boost的反射库PFR
目录 目录 简介 使用方法 限制 总结 简介 Boost.PFR是一个Boost 1.75版本出的C++14的基础反射库,其使用非常简单,非常便捷,但是适用性也比较差,有很多的地方无法使用,适合比较简 ...
- 第七个知识点:随机性如何辅助计算和什么是BPP类问题
第七个知识点:随机性如何辅助计算和什么是BPP类问题 原文地址:http://bristolcrypto.blogspot.com/2014/11/52-things-number-7-how-doe ...