基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档
上篇
前言
为什么在开发中，接口文档越来越成为前后端开发人员沟通的枢纽呢？
随着业务的发张，项目越来越多，而对于支撑整个项目架构体系而言，我们对系统业务的水平拆分，垂直分层，让业务系统更加清晰，从而产生一系统平台和系统，并使用接口进行数据交互。因此可见，业务的不断发展，接口不断增多，很多接口各自寄宿在不同的项目中，如果没有使用api工具进行管理，那么使用和说明将变得非常复杂。所以，接口管理运营应运而生。
在过去的开发中，没有API文档管理工具之前，很多的API文档在什么地方写的都有，有在word写的，有在excel写的，也有对应的项目目录下readme.md写的，每个公司都有每个公司的玩法，但是文档规范极其不统一，甚至出现开发接口更新，但文档不更新，最终导致代码和接口不匹配，开发功能出问题。撸码一分钟，对接三小时。这往往是大家最痛苦的。
因此，在前后端分离的情况下，怎样让前后端开发人员更容易、更直观、更舒服的方式进行沟通交流。在这里，推荐一款轻量级的项目框架Swagger给大家使用。Swagger就是一款让你更好书写API文档的框架
开始
一、 引用Swagger的nuget包
Swashbuckle.AspNetCore
然后就在项目的Nuget依赖里看到刚刚引入的Swagger
二、服务配置环节
在Startup.cs页面中：
编辑 ConfigureServices类：
其中的Url地址不能为空。
三、中间件启动环节
编辑Configure类
注意：路径配置，设置为空，表示直接在根域名（localhost:8001）访问该文件,注意localhost:8001/swagger是访问不到的，去launchSettings.json把launchUrl去掉，如果你想换一个路径，直接写名字即可，比如直接写c.RoutePrefix =”doc”;
到这里之后，我们已经完成了对swagger的添加，F5运行之后，
运行项目之后，我们发现官方默认的是 /WeatherForecast地址，所以我们修改成在域名后面输入/index.html，就可以正常访问了。
如果想修改默认的启动地址，可以在launchSetting.json文件中的launchUrl设置为空，或者删除掉就可以了。
这个时候我们再次启动项目，就可以直接访问根目录下的文件了。
如果启动应用，并导航到 http://localhost:<port>/swagger/V1/swagger.json。生成的描述终结点的文档显示如下json格式。
补充
1. 已经有接口了，但如何添加注释呢？
2. 作为接口使用者，我们关心的是接口的返回内容和响应类型，那我们如何定义描述响应类型呢？
3. 在项目开发中，使用的实体类，又如何在Swagger中展示呢？
4. 在部署项目，引用Swagger既有文档又不需要额外部署，但是如何在开发环境中使用，而在生产环境中禁用呢？
以上的这些内容，会在下一篇讲解Swagger做Api文档做详解。
好了，今天的使用Swagger做Api文档上篇内容就说到这里了，希望能给大家在使用Core开发项目中使用Swagger生产接口文档带来帮助。
总结
1. 从过去手写Api文档，到引入Swagger工具自动生产API接口说明文档，这一转换，让更多的接口可以以通俗易懂的方式展现给开发人员。
2. 后续会继续介绍Swagger的一些高级用法，希望对大家使用Swagger有所帮助。
下篇
前言
回顾上一篇文章《使用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.找不到文件
发现是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. 关注公众号可以获取资料
文章转自微信公众号@元说技术
