在Spring Boot项目中集成API文档生成工具时，许多开发者常遇到一个典型问题：Controller代码逻辑清晰，但生成的OpenAPI文档却结构混乱，接口参数和响应类型显示为简单的“object”，导致文档可读性大幅降低。这通常并非工具本身的缺陷，而是项目配置与注解使用细节上的疏忽所致。
如果你在使用springdoc-openapi（有时被误称为“Trae”）时也遇到了文档生成效果不佳的情况，可以遵循以下系统性的排查与解决方案，快速定位并修复问题。
一、确认并引入正确的SpringDoc依赖
首要步骤是确保项目依赖配置正确。springdoc-openapi是一个独立的开源项目，通过自动扫描@Controller和@RestController注解来生成文档，与已停止维护的springfox无关。依赖版本与Spring Boot主版本的匹配至关重要，错误的starter可能导致扫描完全失效。
具体操作如下：
针对目前主流的Spring Boot 2.6.x或2.7.x版本，建议在pom.xml中添加以下依赖：
若项目已升级至Spring Boot 3.x（需JDK 17及以上），则应更换为以下依赖：
此处需注意一个常见陷阱：项目可能残留旧的springfox依赖。请务必检查并移除所有类似io.springfox:swagger2的依赖项，避免类路径冲突，确保springdoc能够顺利接管API文档的生成任务。
二、启用标准OpenAPI注解并标注Controller
引入正确依赖仅是基础。springdoc默认仅识别遵循OpenAPI 3.0规范（即io.swagger.v3.oas.annotations包）的注解。若Controller类和方法未添加任何注解，生成工具只能解析到基础的方法签名，无法推断接口的详细语义，最终导致文档内容空洞、类型模糊。
要生成专业、清晰的API文档，主动添加以下核心注解是必要步骤：
1. 在Controller类级别，使用@Tag注解声明该控制器的功能模块，这相当于为接口分组，便于在Swagger UI中分类浏览。
@Tag(name = “用户管理”, description = “处理用户注册、查询与状态变更”)
2. 在每个具体的接口方法上，添加@Operation注解。在此处详细描述接口的业务功能、逻辑流程及注意事项。
@Operation(summary = “根据ID获取用户详情”, description = “返回完整用户信息，含角色与权限列表”)
3. 对于复杂的请求体参数，尤其是使用@RequestBody注解的对象，必须使用@Schema注解明确指定其对应的DTO类。否则，文档很可能仅显示无意义的“object”类型。
@Schema(description = “用户创建请求体”, implementation = UserCreateDTO.class)
三、修复Lombok与泛型导致的元数据丢失
Lombok在项目中广泛应用，但其编译时代码生成机制有时会与运行时反射的文档生成工具产生冲突。此外，Java的泛型擦除机制也会导致如ResponseEntity这类复杂返回类型的内部结构在文档中丢失。
针对这些问题，可采取以下解决方案：
1. 在项目根目录下创建lombok.config配置文件，并添加如下行，以增强反射工具对构造器的识别能力：
lombok.anyConstructor.addConstructorProperties = true
2. 对于包含泛型的返回值，需在@ApiResponse注解中显式声明其内部的实际Schema类型：
@ApiResponse(responseCode = “200”, content = @Content(schema = @Schema(implementation = Result.class)))
3. 确保DTO类中的字段未被final关键字修饰，且拥有公共的getter和setter方法。通常使用@Data注解即可，建议编译后检查生成的字节码以作确认。
四、启用校验注解映射与参数解析
我们常在DTO字段上使用如@NotBlank、@Size等校验注解，这些约束不仅用于服务端验证，也应清晰地展示在API文档中。但默认配置下，springdoc可能不会自动解析这些注解。
为使文档完整呈现业务规则，需进行相应配置：
1. 在application.yml配置文件中，启用springdoc的相关特性，例如：
springdoc: show-actuator: true
2. 在DTO字段上，结合使用@Schema描述与校验注解。这样文档既能说明字段的业务含义，也能展示其数据约束。
@Schema(description = “用户名，长度3-20位”) @NotBlank @Size(min = 3, max = 20) private String username;
3. 再次提醒，避免使用final修饰DTO字段，以防SpringDoc在反射解析过程中失败。
五、验证文档生成效果与调试访问路径
完成上述配置后，即可验证文档生成效果。springdoc启动后会同时生成原始的OpenAPI规范JSON和便于浏览的Swagger UI界面。
1. 启动Spring Boot应用，尝试访问Swagger UI的默认路径：
http://localhost:8080/swagger-ui/index.html
2. 若上述地址返回404，请勿慌张。首先检查项目是否引入了Spring Security且未对文档相关路径放行。需确保类似以下路径的访问规则被配置为permitAll()：
/swagger-ui/** 和 /v3/api-docs/**
3. 你也可以直接访问/v3/api-docs端点，获取完整的OpenAPI JSON。通过检查此JSON中的paths字段，可以最直接地确认所有Controller接口是否已被收录，以及每个接口的参数、响应体结构是否已按预期正确描述。
遵循以上五个步骤，即可解决绝大多数因配置和注解使用不当导致的SpringDoc文档生成问题。核心在于理解其工作原理：它依赖于正确的依赖引入、清晰的注解声明以及与工具兼容的代码结构。将这些要点落实到位，一份结构清晰、信息完备的API文档便会自然呈现。