谈谈如何在 .net Core 3.1 WebAPI项目中配置Swagger在线接口文档

前言

与往常一样，喜欢在前言中写关于文章转载或者写下的原因。近日，在做基于钉钉接口的二次开发，从前喜欢pc端的web应用，突然转到移动端的开发时突然发现知识不够用，特别是关于web api这块。前后端分离是局势，在习惯了MVC的代码书写形式时，转到去写前端接口变得无法是从。但是就是在这样的环境逼迫下，我们才不断的去积累新的知识，不断加深自己的功力。

下面进入正题

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

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

首先我们需要安装Swagger的Nuget程序包。这个程序包可以在Nuget管理器中搜索下载。也可以在控制台中通过命令下载，本次例子中我使用的是5.0版本的，在管理器还没有，所以使用控制台通过命令安装：（5.0通过nuget没有适配.net core 3.1的版本）。

在nuget控制台中输入如下代码

Install-Package Swashbuckle.AspNetCore -Version 5.0.0-rc4

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

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

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

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

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

配置好后，我们启用一下看看，出现下面这个页面：这是初始化页面自带的调试文档

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

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

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

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

至此完成。