我已经使用 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>

现在回答你的问题。

The URL http://localhost:8081/swagger-ui/index.html comes from the Swagger-Core library upon which Springdoc is built and thus it will serve the default Petstore example. Though this page can be disabled using the below property in application.properties file.

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

But that holds only for version v1.4.1 and above.

Why /v3/api-docs/swagger-config ?

Now in the URl http://localhost:8081/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config the query parameter configUrl specifies from where to fetch the Springdoc's Swagger-specific configuration file.

Now if you actually hit the URL http://localhost:8081/v3/api-docs/swagger-config, you'll get a config file that's similar to the one below

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

The urls object encompasses individual objects for each API-group. Each API group is shown in the Swagger-UI as shown below

Now, for each API group, these properties are used by Springdoc to render the Swagger-UI by fetching the OpenAPI specification file from the given url and the name is rendered as shown in the above image.

As for the docExpansion property, it's set to none as that setting was explicitly specified in my application.properties

Playing with Properties

• As of Springdoc 1.6.0, the below property is blocked by default for security reasons. Please refer to the comment here for more info. Use springdoc.swagger-ui.queryConfigEnabled=true to enable it at own risk since 1.6.0.

  Use the below property if you want to override the URL from where Springdoc's Swagger configuration file is fetched. Essentially the new URL should return a config file that's similar to the one returned from /v3/api-docs/swagger-config. Defaults to /v3/api-docs/swagger-config

springdoc.swagger-ui.configUrl=/mySpringdocConfig

• Use the below property to override the URL where your Springdoc's Swagger-UI loads. Defaults to /swagger-ui.html, and that's why Swagger-UI is available at http://localhost:8081/swagger-ui.html

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

Conclusion

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

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

Answer 2

您需要访问 swagger ui，而http://localhost:8081/swagger-ui.html不是http://localhost:8081/swagger-ui/index.html加载宠物商店默认 swagger。您可以在以下位置查看解决方法：

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

该 urlhttp://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

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