基于 Spring Boot 3 与 Springdoc-OpenAPI 的 Java 后端接口文档工程化实践

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

@Tag(name = "用户核心接口", description = "提供用户基础信息的增删改查")
@RestController
@RequestMapping("/api/v1/users")
public class UserController {

    @Operation(summary = "根据 ID 获取用户详情", description = "需传入正整数的用户主键 ID")
    @ApiResponse(responseCode = "200", description = "查询成功")
    @ApiResponse(responseCode = "404", description = "用户不存在")
    @GetMapping("/{id}")
    public ResponseEntity<UserResponse> getUserById(
            @Parameter(description = "用户 ID", example = "10001") 
            @PathVariable("id") Long id) {
        // 业务逻辑
        return ResponseEntity.ok(new UserResponse(id, "SpringBean"));
    }
}

/**
 * 订单管理接口
 */
@RestController
@RequestMapping("/api/v1/orders")
public class OrderController {

    /**
     * 创建订单
     *
     * @param request 订单创建请求体
     * @return 订单编号
     */
    @PostMapping
    public ResponseEntity<OrderCreateResponse> createOrder(@RequestBody @Valid OrderCreateRequest request) {
        return ResponseEntity.ok(new OrderCreateResponse("ORD_20240501_001"));
    }
}

public class OrderCreateRequest {

    /**
     * 商品唯一标识
     * @required
     */
    @NotNull
    private Long itemId;

    /**
     * 购买数量
     * @required
     */
    @Min(1)
    private Integer quantity;

    // Getter / Setter 省略
}

<plugin>
    <groupId>com.ly.smart-doc</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>3.0.5</version>
    <configuration>
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <projectName>${project.description}</projectName>
        <!-- 解决跨模块源码读取问题 -->
        <sourceCodePaths>
            <sourceCodePath>
                <path>../common-dto/src/main/java</path>
            </sourceCodePath>
        </sourceCodePaths>
    </configuration>
</plugin>

[Git Commit / PR] 
       ↓
[CI Pipeline 构建与测试] 
       ↓
[执行 Maven 插件生成 openapi.json] 
       ↓
[Swagger-CLI / Redocly 代码检查] 
       ↓
[推送到企业文档中心 (如 YApi / Apifox / 静态网关)]

# GitHub Actions 片段示例
name: Docs CI

on:
  push:
    branches: [ "main" ]

jobs:
  generate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'

      - name: Build OpenAPI Spec
        run: ./mvnw compile smart-doc:openapi

      - name: Lint OpenAPI Spec
        run: npx @redocly/cli lint ./target/smart-doc/openapi.json