参考地址，官网：https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-2.2&tabs=visual-studio

与https://www.jianshu.com/p/349e130e40d5

当一个WebApi完成之后，书写API文档是一件非常头疼的事，因为不仅要写得清楚，能让调用接口的人看懂，又是非常耗时耗力的一件事。在之前的一篇随笔中（https://www.cnblogs.com/taotaozhuanyong/p/11567017.html），记载.Net Framework中WebApi生成文档的时候，通过访问指定的路径，就可以获取到Api文档。在.NET Core中又怎么生成API文档呢？使用Swagger。

为什么使用Swagger作为REST APIs文档成功工具呢？

　　1、Swagger可以生产一个具有互动性的API控制台，开发者可以用来学习和尝试API。

　　2、Swagger可以生产客户端SDK代码用于各种不同的平台上的实现。

　　3、Swagger文件可以在许多不同的平台上从代码注释中自动生成。

　　4、Swagger有一个强大的社区，里面有许多强悍的贡献者。

Swagger简单介绍

Swagger官网：https://swagger.io/irc/

 

Swagger Codegen：通过Codegen可将描述文件生成html和cwiki形式的接口文档，同时也能生成多种语言的服务端和客户端的代码。可以在后面的Swagger Editor中在线生成。

Swagger UI：提供了一个可视化的UI页面 展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入文件和本地部署UI项目。

Swagger Editor：类似于markendown编辑器的编辑Swagger描述文件的编辑器，改编辑器支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

Swagger Inspector：感觉和postman差不多，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。

Swagger Hub：继承了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中跨域完成上面项目的所有工作，需要注册账号，分免费版和收费版。

下面介绍如何在ASP.NET Core中使用Swagger生成API说明文档

.NET Core3.0已经出来了，那我们就基于.NET Core3.0新建一个WebApi项目吧。

这里为了掩饰Swagger的使用，就不创建空项目了，选择ASP.NET Core 3.0

 

 

创建完成会显示这个样子，会给我们默认增加一个WeatherForecastController

 

 

 [ApiController]
 [Route("[controller]")]
 public class WeatherForecastController : ControllerBase
 {
     private static readonly string[] Summaries = new[]
     {
         "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
     };

     private readonly ILogger<WeatherForecastController> _logger;

     public WeatherForecastController(ILogger<WeatherForecastController> logger)
     {
         _logger = logger;
     }

     [HttpGet]
     public IEnumerable<WeatherForecast> Get()
     {
         var rng = new Random();
         return Enumerable.Range(1, 5).Select(index => new WeatherForecast
         {
             Date = DateTime.Now.AddDays(index),
             TemperatureC = rng.Next(-20, 55),
             Summary = Summaries[rng.Next(Summaries.Length)]
         })
         .ToArray();
     }
 }

当我们这个时候运行的时候，会出现404的错误（不知道你们有没有遇到，反正我是遇到了），不要着急，我们做以下修改就行。

首先在Controller中将[Route("[controller]")]====》[Route("api/WeatherForecast")]

再在launchSettings.json中做修改。

 

 这样，我们再访问一下，就成功了。

 

 回归今天的主题。如何使用Swagger。

首先，安装依赖包 Swashbuckle.AspNetCore，选择最新版本的。使用Nuget或者控制台都可以。.Net Core2.0下，这样是没问题的。但是在.Net Core3.0下，最好使用PowerShell进行安装。

Install-Package Swashbuckle.AspNetCore -Version 5.0.0-rc2

 

 添加并配置Swagger中间件

引入命名空间

using Swashbuckle.AspNetCore.Swagger;

在 Startup 类中，导入以下命名空间来使用 OpenApiInfo 类：

using Microsoft.OpenApi.Models;

将 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服务集合中：

在.Net  Core3.0之前：

//注册Swagger生成器，定义一个和多个Swagger 文档
services.AddSwaggerGen(c =>
{
     c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});

但是在.Net Core 3.0中，要这样写