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

Question

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

调出 Swagger 页面

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

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

我将在 Fargate 任务中有几个 API 容器运行，Nginx 将接收来自 Application Load Balancer 和路径（例如 /api/app1）的 REST 请求，它将请求路由到目标应用程序的正确容器端口。

因此，例如，我有三个应用程序：端口 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"。

我想我很接近，但我显然遗漏了一些东西。回顾一下，我只是想改变一下：

默认的SwaggerURL

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 变量并调整 来轻松调整基本路径（例如添加 API 版本号） launchSettings.json 文件来匹配变量的值。

希望这对以后的人有所帮助。

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

How do I change the Swagger default URL and use a custom one?

c#

asp.net-core

swagger

openapi

swashbuckle