（四）如何在.NET Core 3.x 中使用Swagger

在服务端开发过程中，特别是在前后端分离的项目中，后端人员往往会提供出来很多API接口供前端人员使用。一般后端人员会在开发接口的过程中同时维护一份文档（如word、excel），用来说明每一个接口的访问方式、需要的参数、返回的结果等基本信息。但是这种传统的API书写方式很费时间，而且容易造成因为接口文档更新不及时导致的前后端交流成本增加的问题。

基于上述情况，诞生了许多API接口文档自动化生成工具，如Swagger、I/O Docs、apiary.io、Docco、Dexy、Doxygen、TurnAPI。今天重点来说说目前非常流行且实用的用于生成API接口文档的框架Swagger。

Swagger/OpenAPI

Swagger是用于描述REST API的规范，Swagger项目捐赠给了OpenAPI Initiative，现在称为OpenAPI，这两个名称可以互换使用。但是，首选OpenAPI。它使我们都可以理解服务的功能，而无需直接查看实际的实现代码（源代码，网络访问，文档）。Swagger减少了集成API时所需的工作量。同样，它还帮助API开发人员快速，准确地记录其API。

Swagger/OpenAPI规范（Swagger.json或openapi.json）

OpenAPI流程的核心是规范，也就是说Swagger规范是Swagger流程的重要组成部分，默认情况下，Swagger工具会基于我们的API生成名为swagger.json或openapi.json的文档。它是由OpenAPI工具链（或其第三方实现）根据您的服务生成的。它描述了我们API的功能以及如何通过HTTP访问它。它驱动Swagger UI，工具链使用它来启用发现和客户端代码生成。以下是一个简化的OpenAPI规范示例：

{
  "openapi": "3.0.1",
  "info": {
    "title": "API V1",
    "version": "v1"
  },
  "paths": {
    "/api/Todo": {
      "get": {
        "tags": [
          "Todo"
        ],
        "operationId": "ApiTodoGet",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        …
      }
    },
    "/api/Todo/{id}": {
      "get": {
        …
      },
      "put": {
        …
      },
      "delete": {
        …
      }
    }
  },
  "components": {
    "schemas": {
      "ToDoItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "isCompleted": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      }
    }
  }
}

Swagger UI

Swagger UI提供基于Web的UI，该UI提供有关服务的信息。这是使用Swagger规范构建的，并嵌入在Swashbuckle软件包内，因此可以使用中间件将其托管在我们的ASP.NET Core应用中。

也就是说我们可以利用开源项目Swashbuckle为ASP.Net Core Web API生成Swagger文档，Swashbuckle软件包可以轻松地将Swagger集成到我们的.NET Core Web API项目中，它将为我们的项目生成Swagger规范以及Swagger UI。Web UI的样子如下所示：

将Swagger添加到.Net Core 3.1 Web API中

如果你已经成功创建了ASP.Net Core API项目，则下一步是将Swashbuckle.AspNetCore的NuGet包添加到项目中。可以通过NuGet软件包管理器控制台安装，如下命令所示，会安装最新版本的包：

Install-Package Swashbuckle.AspNetCore

也可以通过图形化界面安装：

Swashbuckle软件包中包含三个主要组件：

• Swashbuckle.SwaggerGen：一个Swagger生成器，可直接从我们的控制器和模型构建SwaggerDocument对象，提供生成JSON Swagger文档的功能，这些文档描述了对象，方法，返回类型等。
• Swashbuckle.SwaggerUI：Swagger UI工具的嵌入式版本，该工具使用上述文档提供了丰富的可定制的体验，以描述Web API功能，并包括针对公共方法的内置测试工具功能。
• Swashbuckle.AspNetCore.Swagger：其中包含Swagger对象模型和将SwaggerDocument对象公开为JSON的中间件。

第一步：打开Startup.cs文件，在ConfigureServices方法中加如下代码，将swagger服务添加到中间件：

//将Swagger生成器添加到服务集合
services.AddSwaggerGen(c =>
{
    //定义接口文档的标题、版本、描述信息
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "EFCoreMigration项目的接口文档", Version = "v1.0", Description = "该接口文档会保持最新同步，可以直接在此做接口调试" });
});

第二步：在Configure方法中，启用Swagger中间件：

//启用中间件，使中间件能够将生成的Swagger作为JSON URL提供服务
app.UseSwagger();

//使中间件能够服务于swagger ui（HTML、JS、CSS等）
app.UseSwaggerUI(c =>
{
    //指定Swagger JSON文件的URL
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    //指定Swagger JSON文件的URL，也就是说可以添加多个版本
    c.SwaggerEndpoint("/swagger/v2/swagger.json", "My API V2");
});

第三步：在项目的属性里，修改调试的路径：

第四步：启动应用程序，会进入浏览器的swagger的Web UI界面：

以上就是对swagger的安装以及使用的说明，当然还有许多其他的配置和使用选项，这里暂时就不讲解了。先来谈谈最后一种配置。

添加令牌头

如果您碰巧需要在现有应用程序中安装swagger，则可能需要令牌以使您的请求得到识别，我们上一篇文章正好有JWT令牌头的说明。不加令牌头，现在访问是会报异常的：

 

使用swashbuckle即可轻松完成，需要将其添加到AddSwaggerGen方法中，如下所示：

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            services.AddDbContext(item => item.UseSqlServer(Configuration.GetConnectionString("sqlconn")));

            services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme).AddJwtBearer(options =>
            {
                options.RequireHttpsMetadata = false;
                options.SaveToken = true;
                options.TokenValidationParameters = new TokenValidationParameters()
                {
                    ValidateIssuer = true,
                    ValidateAudience = true,
                    ValidAudience = Configuration["Jwt:Audience"],
                    ValidIssuer = Configuration["Jwt:Issuer"],
                    IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(Configuration["Jwt:Key"]))
                };
            });

            //将Swagger生成器添加到服务集合
            services.AddSwaggerGen(c =>
            {
                //定义接口文档的标题、版本、描述信息
                c.SwaggerDoc("v1", new OpenApiInfo { Title = "EFCoreMigration项目的接口文档", Version = "v1.0", Description = "该接口文档会保持最新同步，可以直接在此做接口调试" });
                //不推荐使用ApiKeyScheme，在版本5以上，推荐使用OpenApiSecurityScheme
                c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
                {
                    Description = @"JWT Authorization header using the Bearer scheme. \r\n\r\n 
                      Enter 'Bearer' [space] and then your token in the text input below.
                      \r\n\r\nExample: 'Bearer 12345abcdef'",
                    Name = "Authorization",
                    In = ParameterLocation.Header,
                    Type = SecuritySchemeType.ApiKey,
                    Scheme = "Bearer"
                });

                c.AddSecurityRequirement(new OpenApiSecurityRequirement()
                {
                    {
                        new OpenApiSecurityScheme
                        {
                            Reference = new OpenApiReference
                            {
                                Type = ReferenceType.SecurityScheme,
                                Id = "Bearer"
                            },
                            Scheme = "oauth2",
                            Name = "Bearer",
                            In = ParameterLocation.Header,
                        },
                        new List()
                        //或者是下面这样
                        //Array.Empty()
                    }
                });

            });
        }

然后在Swagger UI界面上点击Authorize把令牌填上去即可。

再次访问接口正常：

暂时讲解到这里，关于其他的配置和使用选项后续会再次更新此文档，谢谢大家。