一、前言

前后端分离的软件开发方式已逐步成为互联网项目开发的业界标准,前后端分离带来了诸多好处的同时,也带来了一些弊端。

接口文档的维护就是其中之一,起初前后端约定文档规范,开发的很愉快,随着时间推移、版本迭代、接口更改,接口文档维护越来越麻烦。

相信很多前端开发者(请求方)都遇到过实际请求与接口文档不一致的问题

后端开发者(接口提供方)因为时间问题经常来不及更新。
所以仅仅只通过强制来规范大家是不够的,此时Swagger应运而生

什么是Swagger?

Swagger是一个强大的接口文档自动生成工具。

二、引入Swagger包

在Package Manager Console输入如下命令

Install-Package Swashbuckle.AspNetCore -Version 6.0.7

或者在MWebAPI项目右键

选择最新版本Install,安装完成后添加Swagger服务注入及中间件配置

在Startup类的ConfigureServices方法中添加服务注入:

services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo {Title = "Net Core API", Version = "v1"});
});

在Startup类的Configure方法中配置Swagger相关中间件:

app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "Net Core API");
});

F5运行项目

咦,Swagger文档并未展示,这是由于默认启动url未更改

修改launchSetting.json文件中launchUrl如下:

再次F5运行

预想的SwaggerUI展示出来了

三、添加注释

1、首先添加文档说明及作者信息

修改Swagger服务注入部分

services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Title = "Net Core API",
Version = "v1",
Description = "A simple DotNet core web API sample program",
Contact = new OpenApiContact
{
Name = "Sirius",
Email = "1247830052@qq.com",
Url = new Uri("https://www.cnblogs.com/mchao/"),
Extensions = null,
},
License = new OpenApiLicense
{
Name = "免费许可",
Url = new Uri("https://www.cnblogs.com/mchao/"),
Extensions = null,
}
});
});

运行如下:

2、添加生成Controller的注释说明

MWebAPI项目右键->properties->build->output

build项目会生成Controller.xml文件及内容(自动创建更新,无需手动维护)

接着在AddSwaggerGen方法中添加文档路径

services.AddSwaggerGen(c =>
{var xmlPath = Path.Combine(AppContext.BaseDirectory, "Controller.xml");
c.IncludeXmlComments(xmlPath, true);
});

运行如下:

3、添加返回数据的注释说明

MDto项目右键->properties->build->output

接着在AddSwaggerGen方法中添加文档路径

services.AddSwaggerGen(c =>
{
var xmlDtoPath = Path.Combine(AppContext.BaseDirectory, "Dto.xml");
c.IncludeXmlComments(xmlDtoPath, true);
});

运行

这里有个异常,找不到Dto.xml,目前是这样处理的,Dto.xml文件属性 Copy to Outup Direcotry,如哪位道友有其他方案请告知。。。

再次运行

可看到Dto的注释信息

四、Api分组

1、增加分组

在Startup类的ConfigureServices方法中增加doc分组:

c.SwaggerDoc("V2", new OpenApiInfo
{
Title = "Net Core API V2",
Version = "V2",
Description = "A simple DotNet core web API sample program2",
});

在Startup类的Configure方法中增加v2 json路径

app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/V1/swagger.json", "API V1");
c.SwaggerEndpoint("/swagger/V2/swagger.json", "API V2");
});

2、配置分组

给UserInfoController配置V1组

[ApiExplorerSettings(GroupName = "V1")]
public class UserInfoController : Controller

给HomeController配置V2组

[ApiExplorerSettings(GroupName = "V2")]
public class HomeController : Controller

运行:

五、结语

Swagger还有很多好用功能,比如自定义Swagger模板、Swagger开启权限验证等,希望感兴趣的道友继续探索!!!

.Net Core 3.1浏览器后端服务(三) Swagger引入与应用的更多相关文章

  1. .Net Core 3.1浏览器后端服务(一) Web API项目搭建

    一.前言 基于CefSharp开发的浏览器项目已有一段时间,考虑到后期数据维护需要Server端来管理,故开启新篇章搭建浏览器后端服务.该项目前期以梳理服务端知识为主,后期将配合CefSharp浏览器 ...

  2. .Net Core 3.1浏览器后端服务(五) 引入定时任务Quartz.Net

    一.前言 近期项目中遇到一些需求,需要定时写入数据库,定时刷新缓存的问题,因此需要引入任务调度机制. 我的选择是使用 Quartz.Net,使用的版本是 3.2.4 这里强调一点:3.x的版本与2.x ...

  3. .Net Core 3.1浏览器后端服务(四) 你眼中的依赖注入与我相同吗?

    一.前言 DI-Dependency Injection 依赖注入 IoC-Inversion of Control 控制反转 近几年这依赖注入. 控制反转已成为软件开发中不可或缺的一部分,那么该怎么 ...

  4. Orleans[NET Core 3.1] 学习笔记(三)( 3 )服务端配置

    服务端配置 Silo通过SiloHostBuilder和许多补充选项类以编程方式进行配置. Silo配置有几个关键方面: Orleans集群信息 集群提供程序(不知道咋翻译) Silo到Silo和Cl ...

  5. uni-app + Cloudbase——uni-app 项目中如何使用腾讯云开发后端服务

    1 基本介绍 uni-app 是一个基于 Vue.js 的跨端开发框架,一套代码可以发布到 App.小程序.Web 等不同平台 腾讯云开发平台 Cloudbase 提供的 @cloudbase/js- ...

  6. 容易被忽视的后端服务 chunked 性能问题

    容易被忽视的后端服务 chunked 性能问题 标签(空格分隔): springboot springmvc chunked 背景 spring boot 创建的默认 spring mvc 项目 集成 ...

  7. 快速新建简单的koa2后端服务

    既然前端工程化是基于NodeJS,那么选择NodeJs做前后端分离部署也是理所应当的.其实只需要实现静态资源和代理的话,用nginx才是最好的选择,用NodeJS是为了日后能进一步在服务端上实现自动构 ...

  8. vue,vuex的后台管理项目架子structure-admin,后端服务nodejs

    之前写过一篇vue初始化项目,构建vuex的后台管理项目架子,这个structure-admin-web所拥有的功能 接下来,针对structure-admin-web的不足,进行了补充,开发了具有登 ...

  9. 浏览器与服务端请求响应流程与HTTP协议

    浏览器与服务端请求响应流程图: 1.HTTP概要 1.1. 定义 HTTP(HyperText Transfer  Protocol,超文本传输协议)最早就是计算机与计算机之间沟通的一种标准协议,这种 ...

随机推荐

  1. Language Guide (proto3) | proto3 语言指南(七)更新消息类型

    Updating A Message Type - 更新消息类型 如果现有的消息类型不再满足您的所有需要(例如,您希望消息格式有一个额外的字段),但是您仍然希望使用用旧格式创建的代码,不要担心!在不破 ...

  2. form(form基础、标签渲染、错误显示 重置信息、form属性、局部钩子、全局钩子)

    form基础 Django中的Form使用时一般有两种功能: 1.生成html标签 2.验证输入内容 要想使用django提供的form,要在views里导入form模块 from django im ...

  3. PHP-文件、目录相关操作

    PHP-文件.目录相关操作 一  目录操作(Directory 函数允许获得关于目录及其内容的信息) 相关函数: 函数 描述 chdir() 改变当前的目录. chroot() 改变根目录. clos ...

  4. 分布式-springboot基础入门

    B站播放地址:https://www.bilibili.com/video/BV1PE411i7CV?t=51 博客地址:https://www.cnblogs.com/hellokuangshen/ ...

  5. C#委托的进一步学习

    一.委托的说明 namespace LearningCsharp { class Program { //定义一个委托,使用delegate加上方法签名 //将委托理解为存储方法的"数组&q ...

  6. 浅谈Winform控件开发(一):使用GDI+美化基础窗口

    写在前面: 本系列随笔将作为我对于winform控件开发的心得总结,方便对一些读者在GDI+.winform等技术方面进行一个入门级的讲解,抛砖引玉. 别问为什么不用WPF,为什么不用QT.问就是懒, ...

  7. hdu2049 不容易系列之(4)——考新郎(组合,错排)

    题意: n 个数中 m 个数错排的情况个数. 思路: 先从 n 个数中选出 m 个,即 $C_n^m$, 再算出 m 个数的错排数,即 ${f_{\left( m \right)}}$. 错排: 当n ...

  8. POJ 1743 Musical Theme【SAM】

    POJ1743 Musical Theme 要找长度\(\ge 5\)且出现次数\(\ge 2\)并且第一次出现和最后一次出现不重叠的最长子串. 题目条件中,如果对于两个串,在一个串的每个数上都加上相 ...

  9. 2019中国大学生程序设计竞赛(CCPC) - 网络选拔赛(8/11)

    $$2019中国大学生程序设计竞赛(CCPC)\ -\ 网络选拔赛$$ \(A.\hat{} \& \hat{}\) 签到,只把AB都有的位给异或掉 //#pragma comment(lin ...

  10. AtCoder Beginner Contest 179 D - Leaping Tak (DP)

    题意:给你一个数字\(n\)和\(k\)个区间,\(S\)表示所有区间的并的集合,你目前在\(1\),每次可以从集合中选择一个数字向右移动,问有多少种方法从\(1\)走到\(n\). 题解:我们从1开 ...