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

本贴最后更新于 1411 天前,其中的信息可能已经东海扬尘

写在前面的

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

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 标准语法,我的目标是连一根黄线都最好不要出现。

TODOs

后面的版本,很快就会更新的,实现接口的继承和空接口适配。除此之外,也会完善跨文档的锚点跳转,进一步优化文档的阅读体验。

明天就是除夕了,预祝大家新年快乐啦!😆

1 操作
HerbertHe 在 2021-02-10 22:01:59 更新了该帖

相关帖子

欢迎来到这里!

我们正在构建一个小众社区,大家在这里相互信任,以平等 • 自由 • 奔放的价值观进行分享交流。最终,希望大家能够找到与自己志同道合的伙伴,共同成长。

注册 关于
请输入回帖内容 ...
HerbertHe
主营前端, 热衷于造轮子 ~ 现为西部计划服务新疆专项志愿者~ Nuco.Tech Studio 联合创始人 宣城