第60天:存款模块:API文档——SwaggerV3接口规范输出

不写文档的程序员，三个月后连自己都不认识自己的接口

365天，从零手写银行核心系统——第60天

前两天我们聊了监管报送，银行给监管部门“交作业”。

今天聊一个程序员自己的“作业”——API文档。

先问你一个问题：你三个月前写的一个接口，今天回头看，你还记得每个参数是什么意思吗？

不记得？正常。你连上个月写的代码都不想看，更别说三个月前的了。

但问题是：别人要看。前端要看、测试要看、接你盘的新同事要看。你总不能每次都口头说一遍吧？

这时候就需要API文档。

今天我们就来聊聊，怎么用Swagger/OpenAPI 3给银行核心系统生成一份“活”的API文档。

【一、为什么传统的文档方式“不香”？】

以前怎么写API文档？维护一个Word文档或者Wiki页面，手动写上接口地址、参数、返回值。

问题在哪？

代码改了，文档没改。

你加了一个字段，忘了更新文档。前端照着旧文档调接口，报错。然后他来问你，你才发现文档没同步。

文档和代码“失联”了。

你需要的是一份能跟代码同步更新的文档。代码变了，文档自动跟着变。不用手动维护，不用怕忘记更新。

Swagger就是干这个的。

【二、Swagger是什么？OpenAPI又是什么？】

先理清两个概念：

OpenAPI：一份规范（或者说“协议”），定义了API文档应该长什么样——用YAML或JSON格式描述接口地址、参数、返回值、错误码等。它是行业标准，不绑定任何编程语言。

Swagger：围绕OpenAPI规范的一套工具集。其中最常用的就是Swagger UI——把OpenAPI规范文件渲染成一个漂亮的、可交互的HTML页面。你可以在页面上直接点击“Try it out”测试接口。

以前说的Swagger 2（也叫OpenAPI 2.0）早在2017年就停止维护了。现在用的都是OpenAPI 3.x（也叫Swagger 3）。

简单记：OpenAPI是“标准”，Swagger是“工具”。你用Swagger工具，写符合OpenAPI标准的文档。

【三、Spring Boot 3 + OpenAPI 3，怎么配？】

如果你用的是Spring Boot 3.x，不要再碰老掉牙的SpringFox了——它已经不兼容Spring Boot 3。Spring Boot 3只支持OpenAPI 3规范。

正确的做法是用springdoc-openapi。

第一步：加依赖

xml

org.springdoc

springdoc-openapi-starter-webmvc-ui

2.5.0

就这一个依赖，它会自动帮你部署Swagger UI。

第二步：启动项目

启动项目后，访问http://localhost:8080/swagger-ui.html，就能看到自动生成的API文档页面。

第三步：配置基础信息（可选）

在application.yml里加一些自定义配置：

yaml

springdoc:

api-docs:

path: /api-docs OpenAPI规范文件的路径

swagger-ui:

path: /swagger-ui.html Swagger UI访问路径

operations-sorter: method 接口按方法排序

就这三步，你的API文档已经“活”了。所有的Controller、所有的接口、所有的参数，都自动出现在文档里。

不需要写一行额外的文档代码。

【四、用注解把文档写“漂亮”】

自动生成的文档是“能用”，但不够“好看”。因为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到处找接口地址了。

【六、生产环境要注意什么？】

Swagger UI默认是对外开放的。生产环境暴露出去，等于把银行的接口全亮给外人看。

生产环境必须关掉Swagger UI。

yaml

springdoc:

api-docs:

enabled: false

swagger-ui:

enabled: false

或者通过配置中心动态控制，只在开发/测试环境开启。

更好的做法：在网关层做IP白名单，只允许公司内网访问Swagger UI。

【七、今日小总结】

你以前可能| 现在可以

手动维护Word/Wiki文档 | Swagger自动生成

代码改了文档忘了改| 代码和文档同步更新

接口参数靠口头解释| Swagger UI里一目了然

用Postman一个个调试 | Swagger UI直接在线测试

Swagger不是让你“多写一份文档”，是让你“少写一份文档”。代码即文档，文档即代码。

明天我们继续：特殊存款协议——教育储蓄、礼仪存单。

今日任务：打开你正在做的项目，访问/swagger-ui.html，看看你的API文档长什么样。如果还没有集成，今天就加进去。

明日预告：教育储蓄存款——税务优惠规则与支取限制。

365天，我们一起从零开始。