如何更改 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";
                });
}