基于 Spring Boot 3.x 与 Springdoc OpenAPI 的 API 文档工程化：从注解维护到契约驱动落地

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

springdoc:
  api-docs:
    path: /v3/api-docs
    enabled: true
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: method
    # 生产环境建议关闭 try-it-out
    supported-submit-methods: ["get", "post", "put", "delete"]
  show-actuator: false
  default-produces-media-type: application/json

package com.example.dto;

import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Size;

@Schema(description = "创建用户请求体")
public record CreateUserRequest(
    
    @Schema(description = "用户真实姓名", example = "张三")
    @NotBlank(message = "姓名不能为空")
    @Size(max = 20, message = "姓名长度不能超过 20 个字符")
    String realName,

    @Schema(description = "用户年龄", example = "28")
    @NotNull(message = "年龄不能为空")
    Integer age
) {
    // 推荐在 Spring Boot 3 中全面拥抱 Record
}

package com.example.controller;

import com.example.dto.CreateUserRequest;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.Valid;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@Tag(name = "User-API", description = "用户账户生命周期管理接口")
@RestController
@RequestMapping("/api/v1/users")
public class UserController {

    @Operation(summary = "注册新用户", description = "根据传入参数在系统中创建新用户，并下发基础角色")
    @ApiResponses({
        @ApiResponse(responseCode = "201", description = "创建成功"),
        @ApiResponse(responseCode = "400", description = "参数校验失败"),
        @ApiResponse(responseCode = "409", description = "用户已存在")
    })
    @PostMapping
    public ResponseEntity<Void> createUser(@Valid @RequestBody CreateUserRequest request) {
        // 业务逻辑省略...
        return ResponseEntity.status(HttpStatus.CREATED).build();
    }

    @Operation(summary = "按 ID 获取用户详情")
    @GetMapping("/{id}")
    public ResponseEntity<String> getUserById(
            @Parameter(description = "系统用户全局唯一 ID", example = "100234") 
            @PathVariable Long id) {
        return ResponseEntity.ok("User:" + id);
    }
}

<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <version>1.4</version>
    <executions>
        <execution>
            <id>integration-test</id>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
        <outputFileName>openapi.json</outputFileName>
        <outputDir>${project.build.directory}/contract</outputDir>
    </configuration>
</plugin>