如何更改 Swagger 默認 URL 並使用自定義的？

Question

我有一個在.NetCore 3.1 中創建的 API，並使用 Swashbuckle 啟用了 Swagger(OAS3)。 默認情況下，當我的應用程序啟動時，如果使用此 URL 調出 Swagger 頁面：

http://{port}/swagger.index.html

我想自定義 Swagger URL 以便它包含正在運行的應用程序的名稱。 我這樣做的原因是因為我在 AWS Fargate 中運行 Nginx 使用基於路徑的路由。

我將有幾個 API 容器在 Fargate 任務中運行，並且 Nginx 將接收來自應用程序負載均衡器的 REST 請求，並從目標應用程序路徑（例如 /api/app）路由到目標應用程序請求的正確端口 1 .

因此，例如，我有三個應用程序：端口 5000 上的 App1、端口 5001 上的 App2 和端口 5003 上的 App3。

如果用戶向https://api/app1發出請求，Nginx 將檢測路徑並將請求轉發到端口 5000，即 App1 的容器端口。

但是，為了確保出現正確的 Swagger 頁面，我需要將“api/App1”添加到 Swagger 的 URL 以便 Nginx 將正確的請求轉發到容器。 在這種情況下，它是 App1。

換句話說，我希望我的 Swagger URL 看起來像這樣：

https://api/app1/swagger/index.html

我試過的

在我的 Startup.cs 文件中，我添加了以下內容：

// Define prefix for application
private readonly string baseApplicationRoute = "api/app1";

            // Enable OAS3 JSON middleware
            app.UseSwagger(c =>
            {
                c.RouteTemplate = baseApplicationRoute+"/{documentName}/swagger.json";
            });


            app.UseSwaggerUI(c =>
            {
                var endpoint = $"/{baseApplicationRoute}/{version.ToLower()}/swagger.json";
                c.SwaggerEndpoint(endpoint, $"APP1 API - {version}");
                c.RoutePrefix = string.Empty;
            });

這可以編譯和工作，但是它仍然使用相同的 Swagger URL ：

http://{port}swagger.index.html

我認為所有這一切都是在改變 swagger.json 的位置，因為在出現的 Swagger UI 上顯示：

/api/app1/v1/swagger.json

我的 launchSettings.json 文件將“launchUrl”指定為“swagger”。

我想我已經接近了，但我顯然錯過了一些東西。 回顧一下，我只是想改變：

默認 Swagger URL

http://{port}swagger.index.html

給我這里的自定義一個：

http://{port}/api/app1/v1/swagger.index.html

這樣 Nginx 可以檢測到“/api/app1”並路由到正確的容器。

我錯過了什么？

Answer 1

我找到了解決這個問題的方法：

在Startup.cs的配置部分中，我執行了以下操作：

首先，我添加了以下變量：

private readonly string swaggerBasePath = "api/app";

接下來，我使用UseSwagger和UseSwaggerUI配置路徑以使用swaggerBasePath變量：

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

            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint($"/{swaggerBasePath}/swagger/v1/swagger.json", $"APP API - {version}");
                c.RoutePrefix = $"{swaggerBasePath}/swagger";
            });

最后，我修改了 launchSettings.json以指向新的基本路徑：

    "launchUrl": "api/app/swagger",

然后能夠使用以下命令訪問 Swagger 頁面：

https://localhost/api/app/swagger/index.html

我用 Nginx 對此進行了測試，它能夠路由到正確的容器。

通過簡單地修改swaggerBasePath變量並調整launchSettings.json文件以匹配變量的值，我可以輕松地調整基本路徑（例如添加 API 版本號）。

希望這將有助於將來的某人。

Answer 2

（我正在使用.Net 6）

我需要這個，因為我在 api 網關中遇到問題。 所以，我所做的，我保留了我的啟動設置。

啟動設置

"launchUrl": "studentservice/api/swagger",

我在我的Startup.cs文件中進行了這兩項更改。

注意：您的啟動設置 url 和路由前綴 url 應該匹配。

• 在ConfigureService Method中，我添加了 SwaggerDoc

services.AddSwaggerGen(c =>
                {
                    c.SwaggerDoc("student", new OpenApiInfo { Title = "Student Service Api", Version = "1.0" });
}

• 在Configure Method中，我添加了 SwaggerDoc

                app.UseSwagger();

                // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.)
                app.UseSwaggerUI(c =>
                {
                    c.SwaggerEndpoint("/swagger/student/swagger.json", "Student Services Api");
                    c.RoutePrefix = "studentservice/api/swagger";
                });
}