如何更改 Swagger 默认 URL 并使用自定义 URL？

Question

我有一个在 .NetCore 3.1 中创建的 API，并使用 Swashbuckle 启用了 Swagger(OAS3)。默认情况下，当我的应用程序启动时，如果使用此 URL 显示 Swagger 页面：

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

我想自定义 Swagger URL，以便它包含正在运行的应用程序的名称。我这样做的原因是我在 AWS Fargate 中运行 Nginx 时使用基于路径的路由。

我将在 Fargate 任务中运行多个 API 容器，Nginx 将接收来自应用程序负载均衡器和路径（例如 /api/app1）的 REST 请求，它将请求路由到目标应用程序的正确容器端口.

例如，我有三个应用程序：端口 5000 上的 App1、端口 5001 上的 App2 和端口 5003 上的 App3。

如果用户向https://api/app1发出请求，Nginx 将检测路径并将请求转发到端口 5000，这是 App1 的容器端口。

但是，为了确保出现正确的 Swagger 页面，我需要在 Swagger 的 URL 中添加“api/App1”，以便 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 版本号）。

希望这会对将来的某人有所帮助。