别再手动整理接口文档了,Python根据代码自动生成,一秒出活

文档写了一大堆，接口一更新就全乱了。团队里开发懒得动笔，测试追着要格式，前端催着对字段。最崩溃的是，你刚改完代码，忘了同步文档，别人调接口调了半天才发现字段对不上。这种痛，干过后端的人都懂。

我试过Swagger，配置起来有点麻烦，有些字段还得手写注释。后来自己写了个小工具，直接从代码里把接口信息提出来，自动生成文档。思路很简单：用Python读入Flask或FastAPI的路由，提取出URL、方法、参数、返回示例，然后拼成Markdown或JSON。整个过程不需要你额外做任何事，代码写完就能出活。

先说怎么做成这件事。拿Flask举例，应用里的app.url_map有所有注册的路由。遍历一遍，拿到每个视图函数的命名和参数。再读一下函数的文档字符串docstring，里面可以按约定写好请求体和响应的结构。把这些信息塞到一个字典里，用jinja2模板渲染成漂亮的HTML，或者直接输出Markdown挂到项目Wiki上。

关键点是怎么处理参数。我用inspect模块取出函数的签名，对每个参数写个约定：类型写死在类型注解里，默认值从代码里取，必填参数不加默认值就行。这样生成的文档字段列表跟代码完全同步，改一个参数，文档自动跟着变，不可能对不上。用了半年，再没发生过文档和代码打架的情况。

至于返回格式，我习惯在视图函数的顶部定义一个response_example的全局变量，是个dict。工具扫描到这个变量后，直接用json.dumps格式化塞进文档。想怎么写都行，写清楚每个字段的含义就好。遇到分页的接口，我就把page和size参数自动标成查询参数，把返回里的total字段标成整型。这套规则写死了之后，几乎所有接口都能覆盖。

有人担心这种自动生成的东西格式太死板。实际上你可以自定义模板。我写了一个很简单的模板文件，把路由方法拆成请求和响应两块，请求里分路径参数、查询参数、请求体，响应里分状态码和返回结构。谁都能改模板，改成团队习惯的格式。我们还往里面加了请求示例代码块，用Python的requests库演示调用方式，前端直接复制就能用。

把这个工具集成到CI流水线里，每次git push自动跑一遍，生成的文档直接上传到内网Web服务器。同事只需要打开一个固定URL就能看到最新的接口文档，连刷新都不用。测试同学看完文档写用例，对照着字段名一条条测，再也不用来问“那个ID字段是叫userId还是user_id”。

如果你也受够了手动维护文档的苦，可以自己写一个类似的脚本，花一个下午就够了。核心代码就三五十行：读路由、读参数、读描述、拼字符串、存文件。别犹豫，动起手来。写完之后你会觉得，以前花在文档上的时间都白费了。