Springdoc解决SpringBoot3以上版本和Swagger2不兼容的终极指南

后端

2023-09-24 13:38:48

Springdoc：生成 API 文档的不二选择

摘要

Springdoc 是一款功能强大的 API 文档生成工具，可让开发人员轻松创建全面且信息丰富的 API 文档。其与 Spring Boot 的深度集成和对 OpenAPI 3.0 标准的支持使其成为 Spring 应用程序的首选工具。

Springdoc 与 Swagger2 的区别

Swagger2 是 Springdoc 的前身，但 Springdoc 提供了显著的优势：

OpenAPI 3.0 支持： Springdoc 完全兼容 OpenAPI 3.0，这是一种更现代、更丰富的 API 标准。
更好的性能： Springdoc 经过优化，可生成高效且易于使用的 API 文档，而不会影响应用程序性能。
更多特性： Springdoc 提供了广泛的特性，例如代码生成器、文档自定义和扩展支持。

Springdoc 的优势

开箱即用： 无需进行复杂的配置，Springdoc 可轻松集成到 Spring Boot 应用程序中。
OpenAPI 3.0 支持： 生成符合最新 OpenAPI 标准的 API 文档。
JSON 和 YAML 输出： 支持以 JSON 和 YAML 格式生成 API 文档，以便与各种工具兼容。
高度集成 Spring Boot： 与 Spring Boot 应用程序无缝集成，无需编写样板代码。
提供更多特性： 拥有代码生成器、文档自定义和扩展支持等先进特性。

如何使用 Springdoc

1. 添加 Springdoc 依赖项

在项目的 pom.xml 文件中添加以下依赖项：

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

2. 添加 Springdoc 配置

在 Spring Boot 应用程序中，添加以下配置：

@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Spring Boot API Documentation")
                        .description("This is a sample Spring Boot API documentation.")
                        .version("1.0.0"));
    }
}