用showdoc来编写网关接口文档

最近在工作上做了一个网关对外暴露接口,做好后要需要提供接口的文档,然后上网去查找有没有好用的编写接口文档的工具。

接口文档的编写分在线、自己部署2种。在线的网上大家可以搜一下,好多都是提供几个免费的文档,多了后需要付费。自己部署的分为:免费、开源、商业的。这里有一篇文章罗列了一些工具网站:接口文档工具,我就是从这里找到了 showdoc 这个比较满意的工具。

showdoc的官网地址:https://www.showdoc.cc/ 里面有一个示例工程,可以看到一些最终的效果;同时假如你不想搭建一套私有的,你可以进行注册后创建项目,同时拉人进来查看文档。

如何搭建一套showdoc的应用,showdoc的帮助文档写得比较仔细,我因为偷懒,采用了他的docker来进行安装,安装的时候,因为没有严格按照他的步骤,导致了出现一些文件写权限的问题,注意:必须要严格按照文档上的步骤来进行部署 docker 。

部署好首次登录,用户名和密码为:showdoc/123456,进去后别忘记修改密码。

我这里大致罗列一下功能点,这些功能点对于接口文档的编写挺有用的,说明作者是用心了:
1,左侧可以做成树形结构,可以用单独的页面来描述全局性的说明、流程等,用个目录来包含业务接口的页面。
2,有人员权限的划分,基本上对于我们来说,编写、查看这样简单的权限足矣。
3,页面采用markdown,基本上可以满足各种格式的书写;作者特别有心,考虑到一些人对markdown的语法不熟悉,就弄了一些常用的模板,很贴心。

对于其他的一些功能,比如接口测试这样的功能,我个人觉得倒没有这个必要了,术业有专攻,可以用postman来测试的,没有必要这里那么复杂的再实现一个。

最后,提醒一下用 showdoc 的人,别忘记备份了,docker 的备份是 /showdoc_data 这个目录。

发表评论

邮箱地址不会被公开。 必填项已用*标注