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

Question

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

By default, Swagger JSON will be exposed at the following route - "/swagger/{documentName}/swagger.json". If necessary, you can change this when enabling the Swagger middleware. Custom routes MUST include the {documentName} parameter.

为什么模板配置需要此占位符而 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()方法中指定的名称。

以下代码使用 myapi 作为 swagger 文档的名称。

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 UIs

例如，这是我有 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 时，您将看到 select 两个端点之一的下拉列表。

多个 Swagger 文档

您的应用也可以有多个 swagger 文档。例如。你的 'normal' 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 文档，因此为它创建一个占位符是有意义的。即 {documentName}.

我大摇大摆 UI 我现在有 4 个端点：

正常 api 作为 Swagger V2
正常 api 作为 OpenApi V3
遗留 api 作为 Swagger V2
遗留 api 作为 OpenApi V3

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

what is the purpose of {documentname} in the RouteTemplate config?

swagger

swashbuckle

asp.net-core

文档名称

多个 Swagger UIs

多个 Swagger 文档