自动生成的文档是“能用”，但不够“好看”。因为Swagger不知道你的接口是干什么的、参数是什么意思。用几个注解，让文档从“能用”变成“好用”。@Tag：给接口分类java@Tag(name = "账户管理", description = "账户开户、查询、冻结相关接口")@RestController@RequestMapping("/api/account")public class AccountController {// ...}@Operation：描述接口功能java@Operation(summary = "账户开户", description = "创建新账户，返回卡号和账户信息")@PostMapping("/open")public Result openAccount(@RequestBody OpenAccountRequest request) {// ...}@Parameter：描述参数java@Parameter(description = "客户身份证号", required = true, example = "11010119900307663X")@RequestParam String idNumber;@Schema：描述数据模型java@Schema(description = "开户请求")public class OpenAccountRequest {@Schema(description = "客户姓名", required = true, example = "张三")private String name;@Schema(description = "身份证号", required = true, example = "11010119900307663X")private String idNumber;}加上这些注解后，Swagger UI里会显示清晰的字段说明和示例值，前端和测试看了直接就能用。OpenAPI 3用的是@Operation、@Parameter、@Schema，不是Swagger 2时代的@Api、@ApiParam、@ApiModel。别搞混了。
【五、银行核心系统的API文档长什么样？】
结合我们前59天写的代码，你的API文档大概会有这些模块：模块| 接口示例 | 说明客户管理| POST /api/customer/create | 创建客户信息账户管理| POST /api/account/open | 开户存款交易| POST /api/deposit | 存入取款交易| POST /api/withdraw | 支取转账交易| POST /api/transfer | 转账查询余额| GET /api/account/{accountNo}/balance | 余额查询每个接口的请求参数、返回值、错误码，都在Swagger UI里一目了然。更关键的是：Swagger UI支持“在线调试”。前端直接在页面上填参数、点“Execute”，就能看到真实返回结果。不用再拿着Postman到处找接口地址了。
夜雨聆风