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

Question

我已经在我的 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？

Answer 1

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

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

现在回答你的问题。
网址 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 object 包含每个 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 ，这就是为什么 Swagger-UI 在 http://localhost:8081/swagger-ui.html 可用的原因

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

结论

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

引用 here用于自定义 Springdoc 行为的所有支持属性的列表。