Swagger：在 Swagger UI 中更改 api 路由

Question

我在 AKS 上部署了两个 kubernetes 服务，它们从 Nginx 入口控制器接收流量。这两个服务的端点是

https:<dns>/service1

和

https:<dns>/service2

。现在我想为每个服务设置 Swagger。下面是我如何为其中一项服务设置 Swagger UI。

app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/service1/swagger/v1/swagger.json", "API V1");
        });

有了这个配置，我就可以通过

https:<dns>/service1/swagger

访问swagger了。

现在的问题是，在 Swagger UI 中，当我想通过单击“Try it out”按钮然后 Excute 按钮来测试 api 时，Swagger UI 访问的 url 是

https:<dns>/api/v1/contoller

而不是

https:<dns>/service1/api/v1/contoller

。这意味着 Swagger UI 不知道路径

/service1/

的存在。我发现了几个相关的问题，比如这个 How to change base url of Swagger in ASP.NET core 。但它们并不能解决我的问题。我的猜测是我需要为 Swagger 设置基本路径。如果有人能告诉我如何在 ASP.NET core 2.0 中配置 Swagger 的基本路径，我将不胜感激。

Answer 1

更改此：

app.UseSwagger();
app.UseSwaggerUI(c =>
{
  c.SwaggerEndpoint("/service1/swagger/v1/swagger.json", "API V1");
});

对此：

适用于 dotnet core 2.x

app.UseSwagger(c =>
{
#if !DEBUG
  c.PreSerializeFilters.Add((swaggerDoc, httpReq) => swaggerDoc.BasePath = "/service1");
#endif
});
app.UseSwaggerUI(c =>
{
  c.SwaggerEndpoint("./swagger/v1/swagger.json", "API V1");
});

适用于 dotnet core 3.x （Swashbuckle 5.x 预发行版+）

app.UseSwagger(c =>
{
#if !DEBUG
  c.RouteTemplate = "swagger/{documentName}/swagger.json";
  c.PreSerializeFilters.Add((swaggerDoc, httpReq) => swaggerDoc.Servers = new System.Collections.Generic.List<OpenApiServer>
  {
    new OpenApiServer { Url = $"{httpReq.Scheme}://{httpReq.Host.Value}/service1" }
  });
#endif
});
app.UseSwaggerUI(c =>
{
  c.SwaggerEndpoint("./swagger/v1/swagger.json", "API V1");
});

#if !DEBUG ... #endif 对于在本地计算机中调试时访问 swagger ui 是必需的。

注意： 我假设“/service1”与 helm 图表的 value.yaml 文件中的值相同。 （见下文）

...
ingress:
  enabled: true
  annotations: {
    kubernetes.io/ingress.class: "nginx",
    nginx.ingress.kubernetes.io/rewrite-target: /$1
  }
  path: /service1/?(.*)
  hosts:
    - your-aks-subdomain.your-azure-region.cloudapp.azure.com
  tls: []
  #  - secretName: chart-example-tls
  #    hosts:
  #      - chart-example.local

hpa:
...

Answer 2

请您的

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
        {

在此之后使用：

app.UseSwaggerUI(c=>
              {
                   c.SwaggerEndpoint("/service1/swagger/v1/swagger.json", "Giftaway API V1");

这个选项

c.RoutePrefix = "service1";

这会让你

https:<dns>/service1/api/v1/controller

Answer 3

基于https://github.com/apigee-127/swagger-tools/issues/342#issuecomment-391940961和https://github.com/springfox/springfox/pull/1217也许你可以尝试在入口规则中设置 X-forwarded-prefix，如 https://github.com/kubernetes/ingress-nginx/pull/1805#issuecomment-366896998

Answer 4

在您的入口中不要使用此注释

nginx.ingress.kubernetes.io/rewrite-target：/

Answer 5

我正在使用 ASP.NET Core 6 和 Swashbuckle.AspNetCore 6.5，并且 UNOPARATOR 需要进行更改才能正常工作：

        app.UseSwagger(c =>
        {
#if !DEBUG

            c.PreSerializeFilters.Add((swaggerDoc, httpReq) => swaggerDoc.Servers = new List<OpenApiServer>
            {
                // {httpReq.Scheme} is http on deployed version, so hardcoding https
                new OpenApiServer { Url = $"https://{httpReq.Host.Value}/serviceName" }
            });
#endif
        });
        app.UseSwaggerUI();

我不明白的是为什么

httpReq.Scheme

在部署时返回

http

，但我到处都有

https

，所以我可以安全地进行硬编码（尽管对此不满意）。