springdoc.api-docs.path 与 springdoc.swagger-ui.path

在 Spring Boot 应用中使用 springdoc-openapi 集成 Swagger UI 时，springdoc.api-docs.path 和 springdoc.swagger-ui.path 属性用于配置 API 文档和 Swagger UI 页面的访问路径。这些配置项允许你自定义这些资源的访问 URL，使其适应你的应用架构或符合你的个人或团队的偏好。

作用详解

1. springdoc.api-docs.path

   • 这个属性设置 OpenAPI 3 规范生成的 JSON 或 YAML 格式的 API 文档的访问路径。
   • 默认情况下，如果不设置这个属性，API 文档通常可通过 /v3/api-docs 访问。
   • 设置 springdoc.api-docs.path 允许你修改这个路径。例如，设置为 /api-docs 后，你可以通过 http://localhost:<port>/api-docs 访问到这个 API 文档。

2. springdoc.swagger-ui.path

   • 这个属性设置 Swagger UI 页面的访问路径。
   • 默认情况下，Swagger UI 页面通常可以通过 /swagger-ui.html 访问，这是以前版本的 Swagger（使用 springfox）的标准路径。springdoc-openapi 默认路径是 /swagger-ui/index.html。
   • 通过设置这个属性，你可以更改 Swagger UI 的访问路径，例如，如果你设置它为 /swagger-ui.html，那么你可以通过 http://localhost:<port>/swagger-ui.html 来访问 Swagger UI。

使用场景

自定义这些路径的原因可能包括：

• 保持一致性：如果你从使用其他 Swagger 集成（如 springfox）迁移而来，可能希望保持原有的访问路径，减少其他服务或客户端的修改。
• 安全和管理：更改这些路径可以帮助你更好地管理和限制访问这些资源，特别是在生产环境中，可能需要通过特定路径来控制访问权限。
• 个性化和标准化：在大型项目或多个微服务架构中，统一和个性化 API 文档的访问路径可以帮助开发者更快地定位和使用这些文档。

通过这种方式，springdoc-openapi 提供了灵活性，允许开发者根据具体需求调整和设置 API 文档及其 UI 的访问路径。

这两者的区别是什么

在使用 springdoc-openapi 集成 Swagger UI 的上下文中，springdoc.api-docs.path 和 springdoc.swagger-ui.path 指代的路径虽然都与 API 文档相关，但它们服务的内容和目的有所不同。下面是这两个路径的具体区别和用途：

springdoc.api-docs.path

• 功能：这个路径用于访问由 springdoc-openapi 自动生成的 OpenAPI 规范文档，通常以 JSON 格式提供。这份文档是机器可读的，包含了所有由 springdoc-openapi 扫描到的端点的详细信息，如路径、参数、响应类型等。
• 目的：主要用于 API 的规范化描述，可以被各种工具用于自动生成文档、代码生成、API 测试等。它是一个后端服务对外提供的 API 接口的完整描述。
• 默认路径：如果未通过 springdoc.api-docs.path 设置自定义路径，其默认值通常是 /v3/api-docs。

springdoc.swagger-ui.path

• 功能：这个路径用于访问 Swagger UI 页面，这是一个交互式的 Web 页面，开发者和最终用户可以通过它查看 API 文档的详细内容，并且可以直接在页面上测试 API 调用。
• 目的：主要用于提供一个友好的用户界面，让人们可以更容易地理解和使用 API，包括发送请求和查看响应等功能。这个界面是基于 springdoc.api-docs.path 提供的 JSON 或 YAML 文档动态生成的。
• 默认路径：在 springdoc-openapi 中，如果未设置 springdoc.swagger-ui.path，Swagger UI 默认的访问路径是 /swagger-ui.html，但是这实际上会重定向到一个更长的路径 /swagger-ui/index.html。

总结

简而言之，springdoc.api-docs.path 提供了 API 的规范化机器可读描述（JSON/YAML），主要被工具和开发者使用，而 springdoc.swagger-ui.path 提供了一个人类可读的交互式界面，使得实际的 API 消费者能够理解和测试 API。这两个路径虽然关联紧密，但服务的受众和用途有明显的区分。