SpringDoc接口文档

<!-- 显式引入最新 springdoc -->
<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
	<version>2.8.16</version> <!-- 最新稳定版 -->
</dependency>

配置 application.yaml

# 接口文档配置
# 生产环境建议关闭 Springdoc 相关端点
springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    enabled: true

Swagger 配置类

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Spring Boot 3 Swagger Demo")
                        .version("1.0")
                        .description("API 文档示例"));
    }
}

实体类注解（OpenAPI 3 规范）

使用 @Schema 注解描述实体类和字段，支持字段级描述和示例值。

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

@Data
@Schema(description = "用户实体")
public class User {
    @Schema(description = "用户ID", example = "1")
    private Long id;
    
    @Schema(description = "用户名", example = "john_doe")
    private String username;
}

控制器注解（OpenAPI 3 规范）

通过 @Tag 和 @Operation 注解描述接口分组和操作细节。

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
@Tag(name = "用户管理", description = "用户相关接口")
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "获取用户信息", description = "根据ID查询用户")
    public User getUser(@PathVariable Long id) {
        return new User(); // 模拟返回
    }

    @PostMapping
    @Operation(summary = "创建用户", description = "新增用户记录")
    public User createUser(@RequestBody User user) {
        return user; // 模拟返回
    }
}