转载

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

前言

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

回顾上一篇文章 《使用 Swagger Api 文档   ,文中介绍了在 .net core 3.1 中,利用 Swagger 轻量级框架,如何引入程序包,配置服务,注册中间件,一步一步的实现,最终实现生产自动生产 API 接口说明文档。文中结尾也留下了一个让大家思考的问题。在这里,我们重新回顾一下这几个问题

1.  已经有接口了,但如何添加注释呢?

2.  作为接口使用者,我们关心的是接口的返回内容和响应类型,那我们如何定义描述响应类型呢?

3.  在项目开发中,使用的实体类,又如何在 Swagger 中展示呢?

4.  在部署项目,引用 Swagger 既有文档又不需要额外部署,但是如何在开发环境中使用,而在生产环境中禁用呢?

开始

一、为接口方法添加注释

1 .  按照下图所示 连点三次 / 即可添加文档注释

如下所示

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

2. 启用XML 注释

右键 web  项目名称 => 属性 => 生成 ,勾选 输出 下面的 xml 文档文件 ,系统会默认生成一个 , 如下图所示

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

3. 配置服务

在之前注册的 Swagger 服务代码中,添加以下几行代码,引入 xml 文件

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

整体的代码如下:

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

4. 重新编译运行

查看效果

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

注意:如果需要对控制器进行注释说明如下 ,可以将

  c.IncludeXmlComments(xmlPath,true); 这个设置为true,显示效果如下:

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

二、描述响应类型

接口使用者最关心的就是接口的返回内容和相应类型啦。下面展示一下 201 400 一个简单例子:

我们需要在我们的方法上添加: [ProducesResponseType(201)][ProducesResponseType(400)]

然后添加相应的状态说明: <response code="201"> 返回 value 字符串 </response> <responsecode="400"> 如果 id 为空 </response>

最终代码应该是这个样子:

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

效果如下:

<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

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

在控制器中引入接口方法

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

效果如下:

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

四、在生产环境中禁用

可以将 Swagger UI 页面配置在 Configure 的开发环境之中

放到 if(env.IsDevelopment()) 即可。

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

五、隐藏某些接口

如果不想显示某些接口,直接在 controller  上,或者 action  上,增加特性

[ApiExplorerSettings(IgnoreApi = true )]

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

六、忽视Swagger注释警告

启用 XML  注释后会为未记录的公共类型和成员提供调试信息。如果出现很多警告信息    例如,以下消息指示违反警告代码  1591

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

原来是 swagger 把一些 action  方法都通过 xml 文件配置了,如果你不想每一个方法都这么加注释,可以这么配置,在当前项目进行配置,可以忽略警告,记得在后边加上分号   ;1591

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

常见错误

Swagger 使用的时候报错,无法看到列表,这里说下如何调试和主要问题:

1. 找不到文件

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

请在浏览器  = F12 == console  控制台  == 》点击错误信息地址

发现 404 ,说明是找不到指定的文件,可以存在以下情况:

这是因为接口 json 文档定义和调用不是一个

1 、定义:

ConfigureServices 方法中的   services.AddSwaggerGen  注册的一个名字  c.SwaggerDoc("v1", 

2 、调用:

Configure  方法中的  app.UseSwaggerUI(c =>    调用   c.SwaggerEndpoint("/swagger/V1/swagger.json

看看两者是否一致

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

 2. 500 错误无法解析

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

直接链接 http://localhost:xxxxx/swagger/v1/swagger.json ,就能看到错误了

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

这种可以存在以下情况:

1 .  接口请求的方式不明确: 少了 [httpget] [httpPost] 等,导致无法解析

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

总结

1.  通过这一篇的整体学习,我们已经解决了上一篇文章留下的问题,也知道了怎样更好的使用 Swagger 进行开发接口文档,更加方便快捷的使用

2.  从上篇的引用配置启动,到这一篇的升级改造,让接口文档更加通俗易懂。

3.  关注公众号可以获取资料

基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)

原文  http://mp.weixin.qq.com/s?__biz=MzAwNTMxMzg1MA==&mid=2654079133&idx=4&sn=5588c29607ccc64c8601df16e5b46c32
正文到此结束
Loading...