基于.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. 关注公众号可以获取资料