带有 Swagger/OpenAPI 的 ASP.NET Core Web API 文档

作者：Christoph Nienaber 和 Rico Suter

Swagger (OpenAPI) 是一个与语言无关的规范，用于描述 REST API。 它使计算机和用户无需直接访问源代码即可了解 REST API 的功能。 其主要目标是：

• 尽量减少连接分离的服务所需的工作量。
• 减少准确记录服务所需的时间。

.NET 的两个主要 OpenAPI 实现是 Swashbuckle 和 NSwag，请参阅：

• Swashbuckle 入门
• NSwag 入门

OpenAPI 与 Swagger

Swagger 项目已于 2015 年捐赠给 OpenAPI 计划，自此它被称为 OpenAPI。 这两个名称可互换使用。 不过，“OpenAPI”指的是规范。 “Swagger”指的是来自使用 OpenAPI 规范的 SmartBear 的开放源代码和商业产品系列。 后续开放源代码产品（如 OpenAPIGenerator）也属于 Swagger 系列名称，尽管 SmartBear 未发布也是如此。

简而言之：

• OpenAPI 是一种规范。
• Swagger 是一种使用 OpenAPI 规范的工具。 例如，OpenAPIGenerator 和 SwaggerUI。

OpenAPI 规范 (openapi.json)

OpenAPI 规范是描述 API 功能的文档。 该文档基于控制器和模型中的 XML 和属性注释。 它是 OpenAPI 流的核心部分，用于驱动诸如 SwaggerUI 之类的工具。 默认情况下，它命名为 openapi.json。 下面是为简洁起见而缩减的 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，它使用生成的 OpenAPI 规范提供有关服务的信息。 Swashbuckle 和 NSwag 均包含 Swagger UI 的嵌入式版本，因此可使用中间件注册调用将该嵌入式版本托管在 ASP.NET Core 应用中。 Web UI 如下所示：

控制器中的每个公共操作方法都可以从 UI 中进行测试。 选择方法名称可以展开该部分。 添加所有必要的参数，然后选择“试试看!”。

注意

用于屏幕截图的 Swagger UI 版本是版本 2。 有关版本 3 的示例，请参阅 Petstore 示例。

保护 Swagger UI 终结点

调用 MapSwagger().RequireAuthorization 来保护 Swagger UI 终结点。 以下示例保护 swagger 终结点：

using System.Security.Claims;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Services.AddAuthorization();
builder.Services.AddAuthentication("Bearer").AddJwtBearer();

var app = builder.Build();

//if (app.Environment.IsDevelopment())
//{
    app.UseSwagger();
    app.UseSwaggerUI();
//}

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapSwagger().RequireAuthorization();

app.MapGet("/", () => "Hello, World!");
app.MapGet("/secret", (ClaimsPrincipal user) => $"Hello {user.Identity?.Name}. My secret")
    .RequireAuthorization();

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi();

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

在前面的代码中，/weatherforecast 终结点不需要授权，但 Swagger 终结点需要授权。

以下 Curl 传递 JWT 令牌来测试 Swagger UI 终结点：

curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/swagger/v1/swagger.json

有关使用 JWT 令牌进行测试的详细信息，请参阅使用 dotnet user-jwts 生成令牌。

在编译时生成 XML 文档文件。

有关详细信息，请参阅 GenerateDocumentationFile。

后续步骤

• Swashbuckle 入门
• NSwag 入门