基于 Spring Boot 3.x 与 OpenAPI 3.0 的后端文档工程化实践：从契约驱动到 CI/CD 自动化校验

<!-- 注意：Spring Boot 3.x 必须使用 springdoc-openapi 2.x -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

package com.example.doc.controller;

import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

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

    public record CreateUserRequest(
            @NotBlank(message = "用户名不能为空")
            @Size(min = 4, max = 20, message = "用户名长度须在 4-20 之间")
            String username,

            @NotBlank(message = "邮箱不能为空")
            String email
    ) {}

    public record UserResponse(Long id, String username, String email) {}

    // 仅保留核心语义注解，尽量减少 @ApiResponse 堆叠
    @PostMapping
    public ResponseEntity<UserResponse> createUser(@RequestBody CreateUserRequest request) {
        // 业务实现
        return ResponseEntity.ok(new UserResponse(1L, request.username(), request.email()));
    }
}

package com.example.doc;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.payload.PayloadDocumentation.*;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@SpringBootTest
@AutoConfigureMockMvc
@AutoConfigureRestDocs(outputDir = "target/snippets")
class UserControllerRestDocsTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    void shouldCreateUserSuccessfully() throws Exception {
        String jsonPayload = """
                {
                    "username": "chundou",
                    "email": "chundou@example.com"
                }
                """;

        this.mockMvc.perform(post("/api/v1/users")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content(jsonPayload))
                .andExpect(status().isOk())
                .andDo(document("user-create",
                        requestFields(
                                fieldWithPath("username").description("用户名，长度 4-20 字符"),
                                fieldWithPath("email").description("用户邮箱")
                        ),
                        responseFields(
                                fieldWithPath("id").description("系统生成的唯一标识"),
                                fieldWithPath("username").description("用户名"),
                                fieldWithPath("email").description("用户邮箱")
                        )
                ));
    }
}

[Git Push] 
    │
    ▼
[Maven Test (Spring REST Docs)] ──▶ [测试断言失败 ➜ 阻断构建]
    │ (测试通过，产出 Snippets)
    ▼
[Asciidoctor 生成静态 HTML] 
    │
    ▼
[OpenAPI Generator 提取 openapi.json]
    │
    ├─▶ 发布至静态文档服务器 / 内部 Developer Portal
    └─▶ 自动生成前端 TypeScript 类型定义或下游 Feign Client SDK