乐趣区

关于前端:优雅解决-TypeScript-生成接口文档的问题

写在后面的

我这个人平时比拟懒,尤其不是很喜爱写接口文档,在前后端开发的过程中这个需要总是存在的。虽目前主营前端,然而工作室后端的事件也常常是我在管的,所以如何更好的偷懒呢?于是,这个我的项目就诞生了。

TypeScript 有着严格的类型语法标准,prettier 能够帮咱们很好的格式化咱们的 TypeScript 代码,将类型定义文件拆散代码共用。除此之外,nodejs 带给咱们了 JavaScript 脱离浏览器的开发的体验,让咱们能够更随心模块化封装能够通用的库。那么,为什么不能够将 TypeScript 的类型定义用于主动生成 Markdown 的文档呢?得益于在 Markdown 上的积攒,于是说干就干了。

实现思路

TypeScript 次要靠 interface 和 type 进行接口、类型的定义,最后的版本只实现了 interface 接口类型,自 v1.1.0 版本开始曾经能够反对 type 进行类型定义了。

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

曾经实现的库

基于上述的思维,曾经产出了 api-hose 这个库。然而,只是个库而不是框架。为了尽可能使生成的产物更小,我抉择了应用 rollup 打包,并且齐全剔除了 nodejs 的局部。这个库能够集成到本人的命令行工具中去,也是 Nuco 工作室前端团队命令行工具 nuco-cli 的依赖之一。

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

生成的文档完全符合 markdown 规范语法,我的指标是连一根黄线都最好不要呈现。

退出移动版