基于.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>
最终代码应该是这个样子：
效果如下：
<img style="width: 100%;box-sizing: border-box !important;overflow-wrap: break-word !important;visibility: visible !important;height: auto;" data-ratio="0.9589552238805971" data-type="png" data-backh="554" data-backw="578" data-src="https://mmbiz.qpic.cn/mmbiz_png/bHCPBibLoENmWjVkjrxo8B2rnibIKY56ctqQUx94bhw8dQBC8iafFPLg7av9cHZBnYWO8wby1xUnBycSq5F30sfcg/640?wx_fmt=png" data-w="804" />
三、实体类展示添加注释
新建一个 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. 关注公众号可以获取资料
正文到此结束
热门推荐
相关文章
Loading...
![[HBLOG]公众号](https://www.harries.blog/img/qrcode_gzh.jpg)
