手把手叫你搭建一个自己公司的接口文档项目

大家还记得之前阿粉给大家推荐的一个写接口文档的神器么?Run-API,前段时间,因为 Show-Doc 进行网站升级,忽然的一天早上 Run-API 失效了,这下整的阿粉就有崩溃了,啥情况,和阿粉对接的前端也有点懵逼,说接口文档忽然访问不了了,阿粉于是赶紧查看,原来是因为阿粉的接口,是完全的依托于 Show-Doc 的服务器进行了发布,为了防止这种情况的出现,阿粉就开始研究关于 Show-Doc 如何在自己的电脑行搭建一个服务,这样如果 Show-Doc 网站再次升级的时候,也就不会出现这么悲剧的事情了。

关于 Show-Doc

ShowDoc 是一个非常适合 IT 团队的在线文档分享工具,它可以加快团队之间沟通的效率,为什么这么说,因为目前现在很多公司都是建立的前后端分离的项目,很多后端都是专职后台业务逻辑的开发,这时候就会出现,每个人写文档的风格不一致,有些人使用 Excel 有些人使用 Word 表格,有些人使用 Swagger 还有人使用 Show-Doc。

而且尤其是在有新老员工离职交接的时候,交接的接口文档都交接不明白,因为很多都是接口写完了,发给前端,功能上线后,文档没用都删除了,这个时候就得去看代码上面的注释,有注释的还好说,没有注释的,那就让你疯狂的崩溃。不知道代码谁写的,这样岂不是很尴尬,这时候我们就可以在公司内部搭建一个文档类型的服务器,好处有很多呀,比如:

  • 一边调试接口、一边自动生成文档

  • 分配项目成员和团队成员,你可以很方便地进行项目文档的权限管理和团队协作

  • 支持多平台客户端,有win客户端、mac客户端、ios、android等,更方便跨平台使用

据说目前一些知名大厂,比如腾讯、华为、百度、京东、字节跳动 这些公司都在使用,阿粉不知道真的假的,有知道的内部员工可以在后台给大家回复一下确认是否使用,还是 Show-Doc 为了宣传效果做的 “虚假宣传”,话不多说,我们开始搞一下安装部署,然后开始使用吧。

安装Show-Doc

上面这个图是需要你安装好本地服务之后,连接本地服务用的,也就是实际写文档的时候用的,搭建软件在下面呢。

下载网址(Windows下)

Show-Doc 版本其实挺多的,因为阿粉之前的服务器已经到期了,我们就先整个 Windows 的版本来整一下,下载 Windows 版本。

还有一个就是 Linux 下有一键脚本安装,比较方便,

windows下安装推荐使用phpStudy集成环境(如果你不用集成环境,请自身确认开启了”php-pdo-sqlite”和”php-sqlite3”扩展)

下载完成之后就是这个鬼样子,阿粉的版本是8.1.1.3,大家安装完成之后,不用担心影响你本地的所有数据信息,放心就行,没啥影响,不用看着有 Apache 和 Mysql 就担心影响本地,只要端口号不冲突,啥问题没有,在他的四个套件中,前三个套件是有用的,第四个 Nginx 做负载均衡 和第一个 Apache 是有冲突的,阿粉安装完成之后,必须让我关闭一个,另外一个才能启动。

但是不影响,启动了 Apache 的时候 Nginx 就算不管他,都能正常的使用,那阿粉就先留下这个坑,如果有问题,到时候再填上他。

点击左侧菜单“网站”,然后点击右边按钮“管理”-“打开根目录”:

这个时候就有比较坑爹的了,如果你去百度,这时候很多人说让我们去下载源码,然后把文件夹直接拷贝进去,这就会出现问题,访问不到,很难受了,有点坑,我们接下来既然打开了根目录,那么就得往里面放东西,需要我们放的就是 show-doc 的源码。

源码地址如下:

show-doc源码github

如果网络不好的,阿粉也给大家准备了,在后台回复showdoc 阿粉会把下载地址给大家,一个是安装包,一个是源码包,一起发给大家。

下载源码包完成之后,进入该文件夹,全选, 把所有文件复制到刚才打开的网站根目录中(例如根目录是D:\phpstudy_pro\WWW)。需要注意的是,不要单纯把showdoc-master这个文件夹复制过去,要进入showdoc-master把里面的文件都复制出来

拷贝进去之后是上图的样子,然后我们点击修改后就可以看到如下,在 WWW 下就是我们要访问的网址。

当我们把这个部署完成之后,我们就能尝试启动一下看看了,

当我们看到这个页面的时候,就是启动从成功了,我们也部署完成了。

提示php-sqlite没安装的问题,你可以打开“管理”-“php扩展”,确保”php-pdo-sqlite”和”php-sqlite3”开启。如果它没开启,你可以点击它开启。

Show-Doc使用

当我们创建的时候,就是上面这个样子

上面有我们需要的 JSON 转 参数表格,JSON 格式化,还有一些 API 模板 比如:

看到这个,你心动了么?快来安装一波试试吧。

Java Geek Tech wechat
欢迎订阅 Java 极客技术,这里分享关于 Java 的一切。