RouteTemplate 配置中 {documentname} 的目的是什么？

Question

https://github.com/domaindrivendev/Swashbuckle.AspNetCore

默认情况下，Swagger JSON 将在以下路径公开 - “/swagger/{documentName}/swagger.json”。如有必要，您可以在启用 Swagger 中间件时更改此设置。自定义路由必须包含 {documentName} 参数。

为什么模板配置需要这个占位符而 UI 配置不需要？

app.UseSwagger(c =>
{
    c.RouteTemplate = "api-docs/{documentName}/swagger.json";
})
NOTE: If you're using the SwaggerUI middleware, you'll also need to update its configuration to reflect the new endpoints:

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/api-docs/v1/swagger.json", "My API V1");
})

是{documentName}为了什么？是否有动态交换它的功能或什么？因为示例中的 UI 配置是静态配置的。为什么它也不会出现"/api-docs/v1/swagger.json"在 RouteTemplate 配置中？

Answer 1

文档名称

指{documentName}的是您在方法中指定的名称AddSwaggerGen()。

以下代码用作myapiswagger 文档的名称。

builder.Services.AddSwaggerGen(options =>
  options.SwaggerDoc("myapi", new OpenApiInfo { Title = "My API", Version = "v1" })
);

使用UseSwagger如下

app.UseSwagger(options =>
  options.RouteTemplate = "swagger/{documentName}/swagger.json");

导致在以下位置创建 swagger 文件： /swagger/myapi/swagger.json

这意味着您的 Swagger UI 配置必须是

app.UseSwaggerUI(options => {
  options.SwaggerEndpoint("/swagger/myapi/swagger.json", "Swagger v1");
});

Swagger UI 可以基于任何 swagger 文件制作 UI，无论它是否来自该项目。这就是为什么它不包含{documentName}占位符。这些之间没有必然的关系。

多个 Swagger UI

例如，在这个配置中，我有 1 个 Swagger 文档、2 个 swagger 文件和两个 UI 端点。我描述了相同的 API，但一次使用 OpenAPI v3 标准，一次使用旧的 Swagger v2 标准。

builder.Services.AddSwaggerGen(options =>
{
  options.SwaggerDoc("myapi", new OpenApiInfo { Title = "My API", Version = "v1" });
});

app.UseSwagger(options =>
{
  options.SerializeAsV2 = true;
  options.RouteTemplate = "swagger/{documentName}/swaggerV2.json";
});

app.UseSwagger(options =>
{
  options.SerializeAsV2 = false;
  options.RouteTemplate = "swagger/{documentName}/openapiV3.json";
});

app.UseSwaggerUI(options => {
  options.SwaggerEndpoint("/swagger/myapi/openapiV3.json", "OpenApi v3");
  options.SwaggerEndpoint("/swagger/myapi/swaggerV2.json", "Swagger v2");
});

当您转到 swagger UI 时，您将看到一个下拉列表，用于选择两个端点之一。

多个 Swagger 文档

您的应用程序还可以有多个 swagger 文档。例如，您的“普通”API + 一些旧版 API 内容。

options.SwaggerDoc("myapi", new OpenApiInfo { Title = "My API", Version = "v1" });
  options.SwaggerDoc("myapiLegacy", new OpenApiInfo { Title = "My Legacy API", Version = "v1" });

有多种方法可以指定项目的方法何时属于某个 swagger 文档。但最简单的方法是用属性来标记它：

[HttpPost]
[ApiExplorerSettings(GroupName = "myapiLegacy")]
public void Post([Product product)

因此，由于您可以拥有多个 swagger 文档，因此为其创建一个占位符是有意义的。IE，{documentName}。

在我的 swagger UI 中，我现在最终有 4 个端点：

• 普通 api 作为 Swagger V2
• 普通 api 作为 OpenApi V3
• 遗留 api 作为 Swagger V2
• 旧版 api 作为 OpenApi V3