基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)
前言
回顾上一篇文章《使用Swagger做Api文档 》,文中介绍了在.net core 3.1中,利用Swagger轻量级框架,如何引入程序包,配置服务,注册中间件,一步一步的实现,最终实现生产自动生产API接口说明文档。文中结尾也留下了一个让大家思考的问题。在这里,我们重新回顾一下这几个问题
1. 已经有接口了,但如何添加注释呢?
2. 作为接口使用者,我们关心的是接口的返回内容和响应类型,那我们如何定义描述响应类型呢?
3. 在项目开发中,使用的实体类,又如何在Swagger中展示呢?
4. 在部署项目,引用Swagger既有文档又不需要额外部署,但是如何在开发环境中使用,而在生产环境中禁用呢?
开始
一、为接口方法添加注释
1 . 按照下图所示 连点三次 / 即可添加文档注释
如下所示
2.启用XML 注释
右键web 项目名称=>属性=>生成,勾选“输出”下面的“xml文档文件”,系统会默认生成一个,如下图所示
3.配置服务
在之前注册的Swagger服务代码中,添加以下几行代码,引入xml文件
整体的代码如下:
4.重新编译运行
查看效果
注意:如果需要对控制器进行注释说明如下,可以将
c.IncludeXmlComments(xmlPath,true); 这个设置为true,显示效果如下:
二、描述响应类型
接口使用者最关心的就是接口的返回内容和相应类型啦。下面展示一下201和400一个简单例子:
我们需要在我们的方法上添加:[ProducesResponseType(201)][ProducesResponseType(400)]
然后添加相应的状态说明:<response code="201">返回value字符串</response><responsecode="400">如果id为空</response>
最终代码应该是这个样子:
效果如下:
三、实体类展示添加注释
新建一个Movie的实体类,MovieModel
在控制器中引入接口方法
效果如下:
四、在生产环境中禁用
可以将Swagger的UI页面配置在Configure的开发环境之中
放到if(env.IsDevelopment())即可。
五、隐藏某些接口
如果不想显示某些接口,直接在controller 上,或者action 上,增加特性
[ApiExplorerSettings(IgnoreApi = true)]
六、忽视Swagger注释警告
启用XML 注释后会为未记录的公共类型和成员提供调试信息。如果出现很多警告信息 例如,以下消息指示违反警告代码 1591:
原来是swagger把一些action 方法都通过xml文件配置了,如果你不想每一个方法都这么加注释,可以这么配置,在当前项目进行配置,可以忽略警告,记得在后边加上分号 ;1591
常见错误
在Swagger使用的时候报错,无法看到列表,这里说下如何调试和主要问题:
1.找不到文件
请在浏览器 =》F12 ==》console 控制台 ==》点击错误信息地址
发现是404,说明是找不到指定的文件,可以存在以下情况:
这是因为接口json文档定义和调用不是一个
1、定义:
ConfigureServices方法中的 services.AddSwaggerGen 注册的一个名字 c.SwaggerDoc("v1",
2、调用:
Configure 方法中的 app.UseSwaggerUI(c => 调用 c.SwaggerEndpoint("/swagger/V1/swagger.json;
看看两者是否一致
2. 500错误无法解析
直接链接http://localhost:xxxxx/swagger/v1/swagger.json,就能看到错误了
这种可以存在以下情况:
1 . 接口请求的方式不明确:少了[httpget]、[httpPost]等,导致无法解析
总结
1. 通过这一篇的整体学习,我们已经解决了上一篇文章留下的问题,也知道了怎样更好的使用Swagger进行开发接口文档,更加方便快捷的使用
2. 从上篇的引用配置启动,到这一篇的升级改造,让接口文档更加通俗易懂。
3. 关注公众号可以获取资料
基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)相关推荐
- 基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档(上篇)
前言 为什么在开发中,接口文档越来越成为前后端开发人员沟通的枢纽呢? 随着业务的发张,项目越来越多,而对于支撑整个项目架构体系而言,我们对系统业务的水平拆分,垂直分层,让业务系统更加清晰,从而产生一系 ...
- 基于.NetCore3.1搭建项目系列 —— 使用Swagger导出文档 (番外篇)
前言 回顾之前的两篇Swagger做Api接口文档,我们大体上学会了如何在net core3.1的项目基础上,搭建一套自动生产API接口说明文档的框架. 本来在Swagger的基础上,前后端开发人员在 ...
- phpexcel 导出循环增加列数_基于.NetCore3.1搭建项目系列 —— 使用Swagger导出文档 (补充篇)...
前言 在上一篇导出文档番外篇中,我们已经熟悉了怎样根据json数据导出word的文档,生成接口文档,而在这一篇,将对上一篇进行完善补充,增加多种导出方式,实现更加完善的导出功能. 回顾 1. 获取Sw ...
- 基于.NetCore3.1搭建项目系列 —— 使用Swagger导出文档 (补充篇)
前言 在上一篇导出文档番外篇中,我们已经熟悉了怎样根据json数据导出word的文档,生成接口文档,而在这一篇,将对上一篇进行完善补充,增加多种导出方式,实现更加完善的导出功能. 回顾 1. 获取Sw ...
- 基于.NetCore3.1搭建项目系列 —— 认证授权方案之Swagger加锁
1 开始 在之前的使用Swagger做Api文档中,我们已经使用Swagger进行开发接口文档,以及更加方便的使用.这一转换,让更多的接口可以以通俗易懂的方式展现给开发人员.而在后续的内容中,为了对a ...
- 在ASP.NET Core Web API上使用Swagger提供API文档
我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的API文档功能.当设置IISExpress的默认启动路由到Swagger的API文档页 ...
- 浅析如何在Nancy中使用Swagger生成API文档
原文:浅析如何在Nancy中使用Swagger生成API文档 前言 上一篇博客介绍了使用Nancy框架内部的方法来创建了一个简单到不能再简单的Document.但是还有许许多多的不足. 为了能稍微完善 ...
- knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案
knife4j knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望它能像一把匕首一样小巧,轻量, ...
- SpringBoot——SpringBoot集成Swagger生成API文档
文章目录: 1.写在前面 2.步骤详解 2.1 pom文件中添加Swagger依赖 2.2 在application.properties核心配置文件中配置Swagger 2.3 编写需要生成API文 ...
最新文章
- firefly 编译opencv3.3.1, CMake报错
- javadrawstring设置字符大小_LaTex学术写作——编辑文档格式 设置论文标题与摘要...
- intelli idea新建无scala class选项解决方案
- 十佳运动员有奖评选系统_2019年度国际足坛十佳运动员,利物浦三星在列,第十名属私心...
- 关于ORA-01187: cannot read from file because it failed verification tests 的处理方法
- 用c++写成的最小二乘法的源代码
- linux cat 筛选文件夹,Linux 基础命令 -- cat、sort、uniq、wc、head、tail、tee
- 数字电子技术反应时间测试电路(纯电路实现)
- python数据结构-顺序表
- 去除winrar的弹窗广告方法(亲测有效)
- 智慧体检中心管理系统方案/APP/小程序/公众号/网站
- Java之Base64
- 创翼linux版本,创翼电信客户端for Mac-创翼客户端Mac版下载 V1.3.7-PC6苹果网
- python简单实现爬取小说《天龙八部》,并在页面本地访问
- 13/18V系列中频切换开关原理及应用方式
- excel中的stdev和stdevp的区别等系列
- MySQL每天定时12点弹出黑窗口
- 米的换算单位和公式_小学数学单位换算公式(附练习题)
- 常用的html代码 加粗 加亮 字型加大 变色等
- Dual Regression Networks for SISR 环境搭建 | 2020Paper | 【❤️Pytorch 实现❤️】