Springdoc-OpenAPI 使用教程

项目介绍

Springdoc-OpenAPI 是一个用于生成 OpenAPI 3 文档的库，它与 Spring Boot 和 Swagger UI 集成，使得开发者能够轻松地为他们的 REST API 生成文档。该项目支持多种 Spring 生态系统中的技术，如 Spring WebMvc、Spring WebFlux、Spring Data Rest 等。

项目快速启动

添加依赖

首先，在你的 Spring Boot 项目中添加以下依赖：

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

配置应用

在 application.properties 或 application.yml 文件中添加以下配置：

springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.path=/swagger-ui.html

启动应用

启动你的 Spring Boot 应用后，访问 http://localhost:8080/swagger-ui.html 即可看到生成的 API 文档。

应用案例和最佳实践

案例一：集成 Spring Data Rest

Springdoc-OpenAPI 可以与 Spring Data Rest 无缝集成，自动生成对应的数据接口文档。以下是一个简单的示例：

1. 添加 Spring Data Rest 依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-rest</artifactId>
</dependency>

2. 创建一个简单的实体类和仓库：

@Entity
public class Product {
    @Id
    @GeneratedValue
    private Long id;
    private String name;
    // getters and setters
}

@RepositoryRestResource
public interface ProductRepository extends JpaRepository<Product, Long> {}

3. 启动应用后，Springdoc-OpenAPI 会自动为 ProductRepository 生成 API 文档。

最佳实践

• 使用注解详细描述 API：在控制器和实体类中使用 @ApiOperation、@ApiParam 等注解详细描述 API 的功能和参数。
• 自定义文档路径：通过配置文件自定义 API 文档的路径，便于管理和访问。
• 集成 Swagger UI：确保 Swagger UI 的集成，提供友好的文档查看界面。

典型生态项目

Spring WebMvc

Springdoc-OpenAPI 提供了对 Spring WebMvc 的全面支持，适用于传统的 Servlet 环境。

Spring WebFlux

对于响应式编程模型，Springdoc-OpenAPI 也提供了对 Spring WebFlux 的支持，适用于非阻塞的异步环境。

Spring Data Rest

Springdoc-OpenAPI 可以与 Spring Data Rest 集成，自动生成数据接口的文档，简化开发流程。

Spring Security

对于需要安全认证的 API，Springdoc-OpenAPI 提供了对 Spring Security 的支持，确保文档的安全访问。

通过以上模块的介绍和实践，你可以快速上手并深入使用 Springdoc-OpenAPI 项目，为你的 Spring Boot 应用生成详尽的 API 文档。