ASP .Net Core Web Api - Swagger的使用

1.什么是 Swagger

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

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

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

• Swashbuckle 入门

• NSwag 入门

1.1 OpenAPI 与 Swagger

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

简而言之：
OpenAPI 是一种规范。
Swagger 是一种使用 OpenAPI 规范的工具。 例如，OpenAPIGenerator 和 SwaggerUI。

1.2 OpenAPI 规范 (openapi.json)

OpenAPI 规范是描述 API 功能的文档。
该文档基于控制器和模型中的 XML 和属性注释。
它是 OpenAPI 流的核心部分，用于驱动诸如 SwaggerUI 之类的工具。
默认情况下，它命名为 openapi.json。

2.怎么使用 Swagger

本文使用的是Swashbuckle对OpenAPI的实现。

Swashbuckle 有三个主要组件：

Swashbuckle.AspNetCore.Swagger：将 SwaggerDocument 对象公开为 JSON 终结点的 Swagger 对象模型和中间件。

Swashbuckle.AspNetCore.SwaggerGen：从路由、控制器和模型直接生成 SwaggerDocument 对象的 Swagger 生成器。 它通常与 Swagger 终结点中间件结合，以自动公开 Swagger JSON。

Swashbuckle.AspNetCore.SwaggerUI：Swagger UI 工具的嵌入式版本。 它解释 Swagger JSON 以构建描述 Web API 功能的可自定义的丰富体验。 它包括针对公共方法的内置测试工具。

2.1 包安装

右键单击“解决方案资源管理器”>“管理 NuGet 包”中的项目
将“包源”设置为“nuget.org”
确保启用“包括预发行版”选项
在搜索框中输入“Swashbuckle.AspNetCore”
从“浏览”选项卡中选择最新的“Swashbuckle.AspNetCore”包，然后单击“安装”

2.2 配置服务

将 Swagger 生成器添加到 Program.cs 中的服务集合

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

启用中间件为生成的 JSON 文档和 Swagger UI 提供服务

放到生产环境主要是此工具主要是方便开发人员调试使用。
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

启动应用，显示UI:

导航到 https://localhost:/swagger/v1/swagger.json。 生成的描述终结点的文档显示在 OpenAPI 规范 (openapi.json) 中。

3.使用技巧

3.1 自定义和扩展

• API 信息和说明
  使用 OpenApiInfo 类修改 UI 中显示的信息：

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "Open API",
        Description = "An ASP.NET Core Web API for managing ToDo items",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Example Contact",
            Url = new Uri("https://example.com/contact")
        },
        License = new OpenApiLicense
        {
            Name = "Example License",
            Url = new Uri("https://example.com/license")
        }
    });
});

3.2 XML 注释

可以看到，上面的接口信息并没有注释信息，这个需要配置：
1.使用VS生产注释,在项目文件中配置：

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

启用 XML 注释，为未记录的公共类型和成员提供调试信息。 警告消息指示未记录的类型和成员。 例如，指示违反警告代码 1591。
要在项目范围内取消警告，请定义要在项目文件中忽略的以分号分隔的警告代码列表。 将警告代码追加到 $(NoWarn);

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

将 Swagger 配置为使用按照上述说明生成的 XML 文件。

var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));

3.3 注解

[Produces("application/json")]

[Required]

[ApiExplorerSettings(IgnoreApi = true)]

3.4 自定义 UI

默认 UI 既实用又可呈现。 但是，API 文档页应代表品牌或主题。 将 Swashbuckle 组件标记为需要添加资源以提供静态文件，并构建文件夹结构以托管这些文件。

启用静态文件中间件

app.UseHttpsRedirection();
app.UseStaticFiles();
app.MapControllers();

若要插入其他 CSS 样式表，请将其添加到项目的 wwwroot 文件夹中，并在中间件选项中指定相对路径：

if (app.Environment.IsDevelopment())
{
    app.UseSwaggerUI(options => 
    {
        options.InjectStylesheet("/swagger-ui/custom.css");
    });
}