夜雨聆风代码写完了，看着那堆没注释的函数，心里直发毛。文档肯定是得写的，项目经理催，测试要看，接手的人也要骂。可打开空白的Word文档，一个字都不想打。写代码已经榨干了所有耐心，再去描述“这个参数接收一个整数”这种废话，简直要疯。
其实不只是你烦，这事谁都烦。网上搜来搜去，要么是教你用Word模板，要么是让你手写Markdown。更坑的是，费了半天写好文档，代码一改，文档立刻过时。新同事跑来问你“这个接口怎么传参”，你还得对着过期的文档发呆。
后来我发现了一个库，能自动从代码里提取信息，生成排版好的API文档。你把代码跑一遍，所有接口、参数、返回值的结构全自动列出来。甚至你写的注释，也能变成文档里对参数的说明。不用专门写文档，只要写代码的时候顺手加几行注释就行。
这个库叫Swagger UI（或者它的变体Springfox、knife4j，看你用什么语言）。以Java为例，你引入依赖，在配置文件里打开开关。在Controller上加上@Api，在接口方法上标注@ApiOperation，参数的字段加上@ApiModelProperty。启动项目，浏览器打开/swagger-ui.html，一个带搜索框、可展开折叠的漂亮文档页面就出来了。
你不需要额外花时间写文档。你只需要强迫自己把注释写清楚。比如“用户ID，格式为UUID”这种信息，本来就应该写在代码里。 文档是产品的刚需，偷懒的办法是让代码本身成为文档。
我还试过Python版本的FastAPI和drf-spectacular。这俩更省事，你只要用类型注解声明参数类型，页面会自动识别字符串、整数、数组。连注释都不用额外写，代码里的类型信息直接变成文档。
之前有个同事接手一个老项目，没有文档，代码里全是野指针。我帮他加了Swagger，跑了半个小时，接口文档全出来了。他看了页面，对着我说“这玩意比我手写的还全”。自动生成的文档，不会漏掉任何一个接口，不会填错参数类型。
有人担心自动生成的文档不美观。其实这些库提供很多自定义选项，可以改主题颜色，可以添加描述信息，甚至能显示请求示例和返回值示例。一个团队花半天时间，就能让文档页面看起来像大厂出品。
写代码的人都知道，文档不是写给当下的自己看的，是写给两个月后的自己和其他同事看的。既然早晚要写，为什么不找个省事的办法。别跟自己的耐心过不去。试试这个库，把写文档的时间省下来，去喝杯咖啡都比硬着头皮写强。项目需要文档，但不需要我们为文档头疼。