OpenAPI自动化导出需嵌入开发流程才能保持同步；导出必须绑定CI或Git Hooks，DTO字段须加@Schema注解，多环境差异需显式声明，OpenAPI文件应纳入Code Review。
OpenAPI 自动化导出本身不能“保持同步”，它只是把当前代码状态快照成文档；真正起作用的是「导出动作是否嵌入到开发流程中」——比如每次提交前跑一次生成，或在 CI 中校验差异。
导出命令必须绑定到构建流程里
只在本地手动执行 ./gradlew generateOpenApiDocs 或 mvn openapi:generate，文档很快又会脱节。关键是要让导出成为不可跳过的环节。
- CI 流水线中加入检查步骤：对比新生成的
openapi.json和 Git 仓库中已提交的版本，不一致就失败并提示修改 - Git hooks（如
pre-commit）可自动更新文档文件并暂存，避免开发者忘记 - 若用
springdoc-openapi-starter-webmvc-ui，注意它默认只提供运行时/v3/api-docs接口，不生成静态文件；需额外配置springdoc.api-docs.generate-filename并配合插件导出
DTO 字段注解缺失会导致字段无描述
前端看到的 userStatus 字段没有说明，不是导出工具的问题，而是后端没给 @Schema 注解。
PigX UI 前端开发
下载
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
-
@Schema(description = "用户状态：0-正常，1-禁用")必须加在 DTO 字段上，否则 OpenAPI 输出里该字段只有类型、无语义 - 枚举类要配合
@Schema(allowableValues = {"0", "1"})或使用@Parameter(schema = @Schema(implementation = UserStatus.class))，不然前端无法知道取值范围 - 如果用了 Lombok 的
@Data，确保@Schema注解能被正确扫描（部分旧版 springdoc 需要@AllArgsConstructor(onConstructor_ = @Schema)这类写法）
多环境接口差异必须显式声明
开发环境返回 debugInfo 字段，生产环境不返回——这种差异不会自动体现在 OpenAPI 文档里，必须人工干预。
立即学习“前端免费学习笔记（深入）”；
- 不要靠 profile 切换字段逻辑，而应在 OpenAPI 描述中用
x-env扩展字段标记，例如："x-env": ["dev", "test"] - 更稳妥的做法是：为不同环境维护独立的 OpenAPI 文件（如
openapi-dev.yaml），通过 Maven Profile 控制生成哪一份 - 若用 Dify 或自研校验工具做文档比对，记得把环境标识作为比对维度之一，否则会误报“字段删除”
最常被忽略的一点：OpenAPI 文件本身是代码资产，要和源码一样走 Code Review。哪怕只是改了一个 @Schema 描述，也要让同事确认语义是否准确——因为前端可能正基于这段文字写表单校验逻辑。
