前几天粉丝群有小伙伴问,有啥好用的API文档工具推荐,无意间发现了一款工具,这里马不停蹄的来给大家分享一下。
ShowDoc
一个非常适合团队的在线API文档工具,也支持用docker
自建文档服务,不过为了方便演示,我直接用了平台在线服务。官网地址:
https://www.showdoc.com.cn/item/index
可以使用markdown
语法来写API文档、数据字典文档、技术文档、在线excel
文档。但像我这种资深的懒人程序员,其实更看重的是showdoc
的自动化生成文档的特性,它可以从代码注释中自动生成API文档,或者搭配RunApi
客户端(类似postman的api调试工具)一边调试接口、一边自动生成文档。
下边从头演示下,来瞅瞅这玩意好用在哪?
初识 ShowDoc
ShowDoc
新建项目可选常规的API文档、在线表格、或者单页文档(不支持目录分层),允许对项目文档设置访问密码,自定义域名,这里并不是真正意义上的“域名”,只是在文档服务域名后加了一级目录,例如:
www.showdoc.com.cn/程序员内点事
可以复制现有的项目,或直接导入Postman
、swagger
的API接口配置Json文件。提供的开放API是自动化生成文档的关键,先记住有api_key
、api_token
这两个属性,后边详细讲。
进入项目后点击右上角 + 编辑文档,ShowDoc
预置了几种文档模板,也可以把自定义的文档存为模板;支持在线Mock
服务,提前定义好接口的数据格式,先提供在线临时接口,这样就可以和前端同步开发,后边无缝切换;还有个简单的API在线测试功能。
在线表格样式很简洁
导出文档有word
、Markdown
两种格式。
支持版本控制,能看到每次修改的记录,回滚任意一个版本的修改。
在向别人分享在线文档时,如果不想将整个API目录都暴漏,可以选择进行单页面分享。
看到这感觉showdoc
很普通啊,好像没什么特别的地方,上边的这些文档都是需要我们手动书写的,比较繁琐不推荐这么搞,接下来咱们看看如何自动化生成文档。
自动生成文档
showdoc
有三种自动生成API文档的方式:
- 使用Runapi工具自动生成(推荐)
- 使用程序代码注释自动生成
- 自动