net Core WebAPI项目中配置Swagger在线接口文档

在我们团队开发过程中,无论是是前端还是后端开发,都或多或少地被接口文档折磨过。

前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。

其实无论是前端调用后端,还是后端调用后端,都期望有一个好的接口文档。不然随着版本迭代,接口文档往往很容易就跟不上代码了。

在.netCore中,我们可以使用Swagger插件来管理接口,这样我们的接口文档就能够实时更新了,可以避免文档接口跟不上代码的问题。也可以让前后端的开发人员同时进行开发,提高工作效率。

这篇文章主要是如何在.netCore的API项目环境下配置Swagger接口文档插件的。

首先我们需要安装Swagger的Nuget程序包。这个程序包可以在Nuget管理器中搜索下载。也可以在控制台中通过命令下载,本次例子中我使用的是5.0版本的,在管理器还没有,所以使用控制台通过命令安装:

Install-Package Swashbuckle.AspNetCore -Version 5.0.0-rc4

1.png

程序包安装好后,我们需要在Startup类中的ConfigureServices方法中注册Swagger插件服务:

services.AddSwaggerGen(m => m.SwaggerDoc("v1", new OpenApiInfo { Title = "Swagger Demo", Version = "v1" }));

2.png

服务注册好后,我们需要在Startup类中的Configure方法中使用这个服务,使用的时候我们除了使用Swagger服务的同时还需要使用SwaggerUI服务:

app.UseSwagger();
app.UseSwaggerUI(m => m.SwaggerEndpoint("/swagger/v1/swagger.json", "Swagger Demo"));

3.png

到了这里有个小坑需要注意一下:使用服务的时候,json路径的那个版本号和上面注册服务的版本号必须一致

4.png

配置好后,我们启用一下看看,出现下面这个页面:

5.png

这个页面不是我们想要的,出现这个原因是我们没有修改launchSettings.json配置文件。

接下来我们需要修改launchSettings.json文件(不知道这个文件的小伙伴搜一下就能找到了)

6.png

我们需要把WeatherForecast改为swagger的index.html中:

7.png

好了,我们再把项目启动一下看看效果,出现的结果如下图:

8.png

出现这个页面,说明我们已经配置成功了。页面中的接口就是创建API项目时给我们生成的一个接口例子。

点击这个接口蓝色部分展开这个接口,我们可以看到这个接口的请求参数和接口响应内容等

9.png

点击右上角的try it out按钮然后再点击Execute按钮可以在线调试这个接口

10.png

这个接口文档是根据接口开发进度实时更新的,只要后端发布接口服务,这个文档的内容就是最新的,我们试试修改请求参数

我们在这个接口添加name和pwd两个参数

11.png

然后再次运行看看效果

12.png

可以看到的是我们完成接口的开发和修改后重启接口服务,文档会根据我们的接口内容更新的,这样就可以避免人为填写造成的不必要错误,提高前后端对接效率

到这里Swagger在线接口文档的配置就完成了

版权声明:若无特殊注明,本文为《奕独客》原创,转载请保留文章出处。
本文链接:net Core WebAPI项目中配置Swagger在线接口文档 [https://www.yiduk.com/教程资料/25.html]
正文到此结束

热门推荐