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

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 配置中呢？

文件名

{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/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 Doc、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 doc。但最簡單的方法是用屬性標記它：

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

因此，由於您可以擁有多個 swagger 文件，因此為它創建一個佔位符是有意義的。即，{documentName}。

在我招搖的 UI 中，我現在有 4 個端點：

• 作為 Swagger V2 的普通 api
• 普通 api 作為 OpenApi V3
• 舊版 api 作為 Swagger V2
• 遺留 API 作為 OpenApi V3

引用自：https://stackoverflow.com/questions/63960690