springdoc openapi

重要提示： springdoc-openapi v1.8.0是支持 Spring Boot 2.x 和 1.x 的最新开源版本。

对springdoc-openapi v1项目的扩展支持现在可供需要 2023 年之后支持的组织使用。

欲了解更多详情，请随时联系：[email protected]

springdoc-openapi位于 Open Collective 上。如果您❤️这个项目请考虑成为赞助商。

该项目由以下机构赞助

目录

• 完整文档
• 介绍
• 入门
  • springdoc-openapi 与 spring-boot 和 swagger-ui 集成的库
  • 使用 OpenAPI 演示应用程序进行 Spring 启动。
    • 演示应用程序的源代码。
    • 演示 Spring Boot 2 Web MVC 与 OpenAPI 3。
    • 使用 OpenAPI 3 演示 Spring Boot 2 WebFlux。
    • 演示 Spring Boot 2 WebFlux 和功能端点 OpenAPI 3。
    • 使用 OpenAPI 3 演示 Spring Boot 2 和 Spring Hateoas。
  • 在没有 swagger-ui 的情况下将该库集成到 Spring Boot 3.x 项目中：
  • 使用 @ControllerAdvice 进行 REST 错误处理
  • 添加API信息和安全文档
  • spring-webflux 支持带注释的控制器
• 致谢
  • 贡献者
  • 额外支持

完整文档

介绍

springdoc-openapi Java 库有助于使用 Spring Boot 项目自动生成 API 文档。 springdoc-openapi 的工作原理是在运行时检查应用程序，根据 Spring 配置、类结构和各种注释推断 API 语义。

该库自动生成 JSON/YAML 和 HTML 格式页面的文档。生成的文档可以使用swagger-api注释进行补充。

该库支持：

• 开放API 3
• Spring-boot v3（Java 17 和 Jakarta EE 9）
• JSR-303，专门用于@NotNull、@Min、@Max 和@Size。
• Swagger-ui
• OAuth 2
• GraalVM 原生镜像

以下视频介绍了图书馆：

• https://youtu.be/utRxyPfFlDw

对于spring-boot v3支持，请确保使用 springdoc-openapi v2

这是一个基于社区的项目，不由 Spring 框架贡献者 (Pivotal) 维护

入门

springdoc-openapi 与 spring-boot 和 swagger-ui 集成的库

• 自动将 swagger-ui 部署到 Spring Boot 3.x 应用程序
• 文档将以 HTML 格式提供，使用官方 swagger-ui jar。
• 然后，Swagger UI 页面应位于 http://server: port/context-path/swagger-ui.html，并且 OpenAPI 描述将位于以下 json 格式的 url：http://server:port/context -路径/v3/api-文档
  • server : 服务器名称或IP
  • port ：服务器端口
  • context-path ：应用程序的上下文路径
• 文档也可以以 yaml 格式提供，路径如下： /v3/api-docs.yaml
• 将springdoc-openapi-ui库添加到项目依赖项列表中（无需额外配置）：

梅文

   < dependency >
      < groupId >org.springdoc</ groupId >
      < artifactId >springdoc-openapi-starter-webmvc-ui</ artifactId >
      < version >last-release-version</ version >
   </ dependency >

摇篮

implementation ' org.springdoc:springdoc-openapi-starter-webmvc-ui:latest '

• 此步骤是可选的：对于 HTML 格式的 swagger 文档的自定义路径，请在 spring-boot 配置文件中添加自定义 springdoc 属性：

 # swagger-ui custom path
springdoc.swagger-ui.path =/swagger-ui.html

使用 OpenAPI 演示应用程序进行 Spring 启动。

演示应用程序的源代码。

使用 OpenAPI 3 演示 Spring Boot 3 Web MVC。

使用 OpenAPI 3 演示 Spring Boot 3 WebFlux。

演示 Spring Boot 3 WebFlux 和功能端点 OpenAPI 3。

演示 Spring Boot 3 和 Spring Cloud Function Web MVC。

演示 Spring Boot 3 和 Spring Cloud Function WebFlux。

演示 Spring Boot 3 和 Spring Cloud Gateway。

在没有 swagger-ui 的情况下将该库集成到 Spring Boot 3.x 项目中：

• 文档将在以下 json 格式的 URL 中提供：http://server:port/context-path/v3/api-docs
  • server : 服务器名称或IP
  • port ：服务器端口
  • context-path ：应用程序的上下文路径
• 文档也将以 yaml 格式提供，路径如下： /v3/api-docs.yaml
• 将库添加到项目依赖项列表中。 （无需额外配置）

梅文

   < dependency >
      < groupId >org.springdoc</ groupId >
      < artifactId >springdoc-openapi-starter-webmvc-api</ artifactId >
      < version >last-release-version</ version >
   </ dependency >

摇篮

implementation ' org.springdoc:springdoc-openapi-starter-webmvc-ui:latest '

• 此步骤是可选的：对于 Json 格式的 OpenAPI 文档的自定义路径，请在 spring-boot 配置文件中添加自定义 springdoc 属性：

 # /api-docs endpoint custom path
springdoc.api-docs.path =/api-docs

• 此步骤是可选的：如果要禁用springdoc-openapi端点，请在spring-boot配置文件中添加自定义 springdoc 属性：

 # disable api-docs
springdoc.api-docs.enabled =false

使用 @ControllerAdvice 进行 REST 错误处理

要自动生成文档，请确保所有方法都使用注释声明 HTTP 代码响应：@ResponseStatus。

添加API信息和安全文档

该库使用 spring-boot 应用程序自动配置包来扫描 spring bean 中的以下注释：OpenAPIDefinition 和 Info。这些注释声明 API 信息：标题、版本、许可证、安全性、服务器、标签、安全性和 externalDocs。为了获得更好的文档生成性能，请在 Spring 托管 bean 中声明@OpenAPIDefinition和@SecurityScheme注释。

spring-webflux 支持带注释的控制器

• 文档也可以以 yaml 格式提供，路径如下：/v3/api-docs.yaml
• 将库添加到项目依赖项列表中（无需额外配置）

梅文

   < dependency >
      < groupId >org.springdoc</ groupId >
      < artifactId >springdoc-openapi-starter-webflux-ui</ artifactId >
      < version >last-release-version</ version >
   </ dependency >

摇篮

implementation ' org.springdoc:springdoc-openapi-starter-webmvc-ui:latest '

• 此步骤是可选的：对于 HTML 格式的 swagger 文档的自定义路径，请在 spring-boot 配置文件中添加自定义 springdoc 属性：

 # swagger-ui custom path
springdoc.swagger-ui.path =/swagger-ui.html

springdoc-openapi库托管在 Maven 中央存储库上。可以在以下位置查看和访问这些工件：

发布：

• https://s01.oss.sonatype.org/content/groups/public/org/springdoc/。

快照：

• https://s01.oss.sonatype.org/content/repositories/snapshots/org/springdoc/。

致谢

贡献者

由于贡献者的宝贵贡献，springdoc-openapi 具有相关性并定期更新。

感谢大家的支持！

额外支持

• Spring 团队 - 感谢他们的支持，分享了 Spring 项目的所有相关资源。
• JetBrains - 非常感谢您支持 springdoc-openapi 项目。