怎样生成并维护 API 文档？

直接回答

可用匹配Boot版本的springdoc-openapi生成OpenAPI描述，并由Swagger UI等界面展示与试用；规范、生成器和界面是不同角色。自动提取能减少重复，但不能自动补齐业务权限、错误语义和兼容承诺，也不能用页面能打开代替契约测试。

讲清原理

Boot4应按springdoc兼容表选择对应主线，不能沿用旧Springfox或任意Swagger2配置。注解可补示例、字段和响应说明，实际接口类型、验证与状态也要保持一致。

文档可参与客户端生成与契约校验，但变更仍需检查旧调用方。生产UI及描述文件是否开放应按需求配置，示例不能放真实令牌、密码或内部地址。

例子与易错点

提交接口变更时同时检查OpenAPI差异和代表性请求，确认参数必需性、分页和错误响应正确。不要把“文档随代码自动生成”当作无需审阅，因为代码也可能表达错契约。

相关题：第 26 题、第 38 题、第 56 题。