从 Java 代码生成 RESTful API 文档的解决方案

核心原理

通过解析 Java 代码中的注解和类结构，自动生成符合 OpenAPI 规范的文档。关键要素：

1. 注解驱动：利用 @RestController、@GetMapping 等 Spring 注解识别接口
2. 反射机制：扫描类路径获取控制器和方法信息
3. 模型提取：解析 DTO 类结构生成数据模型定义

实现步骤（基于 Spring Boot）

1. 添加依赖

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

2. 控制器注解示例

@RestController
@RequestMapping("/api/users")
public class UserController {

    @Operation(summary = "获取用户详情")
    @GetMapping("/{id}")
    public ResponseEntity<UserDTO> getUser(
        @Parameter(description = "用户ID") @PathVariable Long id) {
        // 业务逻辑
    }

    @Operation(summary = "创建用户")
    @PostMapping
    public ResponseEntity<UserDTO> createUser(
        @io.swagger.v3.oas.annotations.parameters.RequestBody(
            description = "用户数据"
        ) @Valid @RequestBody UserCreateRequest request) {
        // 业务逻辑
    }
}

3. DTO 模型定义

public class UserDTO {
    @Schema(description = "用户ID", example = "1001")
    private Long id;
    
    @Schema(description = "用户名", example = "张三")
    private String name;
    
    // Getter/Setter
}

文档生成与访问

1. 自动生成：启动应用后自动生成 OpenAPI 规范
2. 交互文档：访问 http://localhost:8080/swagger-ui/index.html
3. JSON 格式：获取原始描述 http://localhost:8080/v3/api-docs

关键注解说明

高级配置

在 application.yml 中添加自定义配置：

springdoc:
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger
    display-request-duration: true
  default-consumes-media-type: application/json
  default-produces-media-type: application/json

生成效果说明

1. 自动分组：按控制器分类接口
2. 参数验证：显示 @NotNull 等验证规则
3. 响应示例：根据 DTO 生成示例数据
4. 在线测试：支持直接在文档界面调用 API

此方案通过代码即文档（Code as Documentation）方式，确保文档与代码实时同步，减少维护成本。实际应用中可结合 CI/CD 流程自动生成文档站点。