我已经使用 springdoc 安装了 OpenAPI 3，但是 URL 很奇怪。我可以将其更改为预期值吗？

Posted 2023-03-10

【中文标题】我已经使用 springdoc 安装了 OpenAPI 3，但是 URL 很奇怪。我可以将其更改为预期值吗？

【英文标题】：I have installed OpenAPI 3 using springdoc, but the URL is strange. Can I change it to the expected value?

【发布时间】：2021-04-25 11:44:39

【问题描述】：

我在我的 Java 项目的 pom 文件中使用以下工件安装了 swagger-ui：

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.5.2</version>
   </dependency>

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-security</artifactId>
      <version>1.5.2</version>
   </dependency>

当我转到此 URL 时，我可以查看我的 RESTful 端点的 swagger ui

http://localhost:8081/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config

但不是这个链接

http://localhost:8081/swagger-ui/index.html

这是为什么？如何将其更改回预期的 URL？

【参考方案1】：

您需要访问http://localhost:8081/swagger-ui.html 的招摇用户界面，而不是加载宠物商店默认招摇的http://localhost:8081/swagger-ui/index.html。您可以在

查看解决方法

https://github.com/springdoc/springdoc-openapi/issues/43

网址http://localhost:8081/swagger-ui.html 将始终重定向到http://localhost:8081/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config。

您可以在 application.properties 中使用以下内容进行自定义

springdoc.api-docs.path=/api-docs 
springdoc.swagger-ui.path=/swagger-ui-custom.html

现在 URL http://localhost:8081/swagger-ui-custom.html 将被重定向到 http://localhost:8081/swagger-ui/index.html?configUrl=/api-docs/swagger-config。

【参考方案2】：

首先，以下依赖与您提到的问题无关。

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-security</artifactId>
    <version>1.5.2</version>
</dependency>

现在回答你的问题。

URL http://localhost:8081/swagger-ui/index.html 来自构建 Springdoc 的 Swagger-Core 库，因此它将为默认的 Petstore 示例提供服务。虽然可以使用application.properties 文件中的以下属性禁用此页面。

springdoc.swagger-ui.disable-swagger-default-url=true

但这仅适用于 v1.4.1 及更高版本。

为什么是 /v3/api-docs/swagger-config ？

现在在 URl http://localhost:8081/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config 中，查询参数 configUrl 指定从何处获取 Springdoc 的 Swagger 特定配置文件。

现在，如果你真的点击了 URL http://localhost:8081/v3/api-docs/swagger-config，你会得到一个类似于下面的配置文件

  "configUrl": "/v3/api-docs/swagger-config",
  "docExpansion": "none",
  "urls": [
    
      "url": "/v3/api-docs/default",
      "name": "default"
    
  ],
  "validatorUrl": ""

urls 对象包含每个 API 组的各个对象。每个 API 组都显示在 Swagger-UI 中，如下所示

现在，对于每个 API 组，Springdoc 使用这些属性通过从给定的 url 获取 OpenAPI 规范文件来呈现 Swagger-UI，并且如上图所示呈现 name。

至于docExpansion 属性，它设置为none，因为该设置已在我的application.properties 中明确指定

玩转属性

如果要覆盖从其中获取 Springdoc 的 Swagger 配置文件的 URL，请使用以下属性。本质上，新 URL 应该返回一个类似于从/v3/api-docs/swagger-config 返回的配置文件。默认为/v3/api-docs/swagger-config

springdoc.swagger-ui.configUrl=/mySpringdocConfig

使用以下属性覆盖 Springdoc 的 Swagger-UI 加载的 URL。默认为/swagger-ui.html，这就是为什么在http://localhost:8081/swagger-ui.html 上可以使用 Swagger-UI

springdoc.swagger-ui.path=/mySwagger-UIPath

结论

我认为不可能从 URL 中删除 ?configUrl=/v3/api-docs/swagger-config，因为它始终可用并指向将获取 Srinfdoc 配置文件的位置，如果不可用将导致获取配置文件时出错，从而使 Swagger-UI 无用。此外，由于框架本身正在使用它，因此您不想摆脱它。

请参阅here 以获取所有支持的属性列表以自定义 Springdoc 的行为。