我把API注释自动生成文档的流水线跑了半年，承认光靠工具堆不出好文档

2026年5月5日 34 次浏览

我用了半年时间把团队的API注释自动生成管道打磨成型。从swagger-jsdoc到tsoa，从全量构建到增量缓存，从放任自流到lint+AI辅助审核，我交了不少学费。这篇文章不讲方法论，而是复盘我踩过的坑：工具选型怎么妥协、CI设计怎么得罪DevOps、质量控制如何让团队从骂娘到认同，以及如何把文档从开发者专属变成全员可用的沟通资产。

标签：