最近在工作上做了一个网关对外暴露接口，做好后要需要提供接口的文档，然后上网去查找有没有好用的编写接口文档的工具。
接口文档的编写分在线、自己部署2种。在线的网上大家可以搜一下，好多都是提供几个免费的文档，多了后需要付费。自己部署的分为：免费、开源、商业的。这里有一篇文章罗列了一些工具网站：接口文档工具，我就是从这里找到了 showdoc 这个比较满意的工具。
showdoc的官网地址：https://www.showdoc.cc/ 里面有一个示例工程，可以看到一些最终的效果；同时假如你不想搭建一套私有的，你可以进行注册后创建项目，同时拉人进来查看文档。
如何搭建一套showdoc的应用，showdoc的帮助文档写得比较仔细，我因为偷懒，采用了他的docker来进行安装，安装的时候，因为没有严格按照他的步骤，导致了出现一些文件写权限的问题，注意：必须要严格按照文档上的步骤来进行部署 docker 。
部署好首次登录，用户名和密码为：showdoc/123456，进去后别忘记修改密码。
我这里大致罗列一下功能点，这些功能点对于接口文档的编写挺有用的，说明作者是用心了：
1，左侧可以做成树形结构，可以用单独的页面来描述全局性的说明、流程等，用个目录来包含业务接口的页面。
2，有人员权限的划分，基本上对于我们来说，编写、查看这样简单的权限足矣。
3，页面采用markdown，基本上可以满足各种格式的书写；作者特别有心，考虑到一些人对markdown的语法不熟悉，就弄了一些常用的模板，很贴心。
对于其他的一些功能，比如接口测试这样的功能，我个人觉得倒没有这个必要了，术业有专攻，可以用postman来测试的，没有必要这里那么复杂的再实现一个。
最后，提醒一下用 showdoc 的人，别忘记备份了，docker 的备份是 /showdoc_data 这个目录。