优雅解决 TypeScript 生成接口文档的问题

Posted 2021-10-05 HerbertHe

写在前面的

我这个人平时比较懒，尤其不是很喜欢写接口文档，在前后端开发的过程中这个需求总是存在的。虽目前主营前端，但是工作室后端的事情也经常是我在管的，所以如何更好的偷懒呢？于是，这个项目就诞生了。

TypeScript 有着严格的类型语法规范，prettier 可以帮我们很好的格式化我们的 TypeScript 代码，将类型定义文件分离代码共用。除此之外，nodejs 带给我们了 javascript 脱离浏览器的开发的体验，让我们可以更随心模块化封装可以通用的库。那么，为什么不可以将 TypeScript 的类型定义用于自动生成 Markdown 的文档呢？得益于在 Markdown 上的积累，于是说干就干了。

实现思路

TypeScript主要靠interface和type进行接口、类型的定义，最初的版本只实现了interface接口类型，自 v1.1.0版本开始已经可以支持type进行类型定义了。

在业务层我将interface分为了两类，即 Request Interface 和 Simple Interface 。区别在于 Request Interface 会有 prefix 和 suffix 的概念，利用前缀和后缀可以区别两种接口。所有的文档都是基于正则表达式和对应的模板匹配实现的，分离了解析层、渲染层和导出层，这样可以更加方便对代码进行debug。

已经实现的库

基于上述的思想，已经产出了 api-hose 这个库。但是，只是个库而不是框架。为了尽可能使生成的产物更小，我选择了使用rollup打包，并且完全剔除了nodejs的部分。这个库可以集成到自己的命令行工具中去，也是Nuco工作室前端团队命令行工具nuco-cli的依赖之一。

因为是正则实现的，因此实现的是增量更新，会随着迭代进一步解决可能会存在的bug和实现新的feature。现在可能的bug基本上都测试过了，欢迎使用并踢issue。

生成的文档完全符合markdown标准语法，我的目标是连一根黄线都最好不要出现。