基于 apidoc 生成在线接口文档 （实时更新）（linux系统）

基于 apidoc 生成在线接口文档 （实时更新）（linux系统） 动态加载，热部署
背景：
规范开发人员的接口文档
文档统一管理，防止本地文档版本不统一
远程部署，保证文档的统一性
主要还是解决，不用每个人去装一套环境
缺点：
1. 容错性太垃圾，可以优化
2. 需要一台服务器
3. 没有测试过多人操作
备注：
如若不想使用，远程文档连接的话，可以本地安装node.js 和 apidoc
本地安装，一路下一步，需要注意就是环境变量配置
apidoc 直接本地生成

系统环境 ：CentOS Linux release 7.3.1611
查看当前操作系统版本信息
cat /proc/version
查看当前系统的发行信息
cat /etc/centos-release 或 cat /etc/issue

环境
node.js apidoc安装包 ，tomcat ，git/svn

1). node.js 安装
官网地址：https://nodejs.org/dist/
1.下载node.js https://nodejs.org/dist/latest-v8.x/node-v8.1.4-linux-x64.tar.gz
或者本地下载上传服务器
2. 复制到自己好管理的目录，任意目录都可以

3. 解压目录并且重名名（重命名是为了好配置环境变量，可以使用复制文件夹的方式重命名）
tar zxvf node-v10*
. 配置环境变量 (node_home = 安装的路径)
vi /etc/profile
添加
export NODE_HOME=/home/node/node-v10.9.8
export PATH=$NODE_HOME/bin:$PATH
保存
5. 检验安装是否成功 node -v npm -v
显示版本号成功
安装很简单，基本按照步骤走，一次就能成功，需要注意的就是 读写文件的权限问题
2). 使用apidoc
apidoc是一个轻量级的在线REST接口文档生成系统，支持多种主流语言，包括Java、C、C#、PHP和JavaScript等。使用者仅需要按照要求书写相关注释，就可以生成可读性好、界面美观的在线接口文档

 

 

1.使用npm 安装，安装命令为 npm install apidoc -g
检测安装 apidoc -h
2.使用apidoc
命令行
apidoc中的重要命令和参数。apidoc的命令格式如下：

 

生成命令
apidoc -i src/ -o apidoc/
配置文件
apidoc.json :apidoc的项目级配置文件 ，必须位于项目的根目录
最好是和api的项目的src的文件夹同级，新建apidoc.json的配置文件

 

 

配置文件配置项

 

示例

 

Params
apidoc中最核心的东西就是参数（params）的书写，本节介绍apidoc中一些重要的params
直接提供一个例子

 

 

注意点
1，注解加载代码注释里边，不能有特殊符号，最后一行不能有回车符，不能有空行
不能用 return 的自定义注释 ，否则都有可能造成生成失败
2. 注解和参数 之间最好有空格隔开，否则也有可能引起生成失败
错误示例：@apiName我是接口
正确示例：@apiName 我是接口
3.常用注解 （[]表示可选参数）
@apidoc 必填 格式为 @api {method} path [title]

 

@apiDescription 对接口进行描述 ，格式 @apiDescription text
@apiGroup 表示分组名称，它会被解析成一级导航栏菜单
@apiName 表示接口名称
@apiParam 定义 API 接口需要的请求参数

 

 

示例：@apiParam {String} name 书籍名称
多个参数的示例：
@apiParam {String} name 书籍名称
@apiParam {String} age 年龄
@apiSuccess
表示请求成功时的一个返回字段。
@apiError 表示请求失败时的一个返回字段。
格式为 @apiError [(group)] [{type}] field [description]
示例：@apiError {String} code 返回码
@apiParamExample 表示一个请求范例。
格式为 @apiParamExample [{type}] [title] example
示例：
@apiParamExample {json} 请求示例
{
"name":"魂破九天"
}
其他可以参考官方文档 ：http://apidocjs.com/#configuration
或则博客地址： https://www.cnblogs.com/minsons/articles/7154090.html
至此已经实现使用apidoc 生成接口文档了，生成目录如下，访问index

 

4.生成了idea和eclipse的注释模板，有接口，只需填写接口信息和特殊注解即可
3). 安装git/svn 检出更新代码
  新建git安装的文件夹 mkdir git
官网 HYPERLINK "HYPERLINK "HYPERLINK "HYPERLINK "HYPERLINK "https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/"https://git-scm.com/下载安装包

 

 

 

 

 

选择版本下载， 上传到服务器新建的目录下
  tar zxvf git-2.8.6.tar.gz 安装完成，不需要配置环境变量
新建代码文件夹 work ,mkdirt work
进入work文件夹，检出代码 git clone 代码地址

4）脚本实现更新代码,并且生成代码部署tomcat
1. 准备一个可以启动的tomcat
2. 新建脚本 , touch apigen.sh --> chmod 700 apigen.sh
3. 编辑生成文件部署tomcat脚本，直接贴出脚本代码

# $2 代码原始文件 $1 接口文档文件 入口参数
mkdir $1 #新建接口文档的目录，根据不同的项目名新建，主要为了支付本地下载生成文件
rm -rf $1 # 如果接口文档目录存在，删除掉里边内容重新生成
apidoc -i /home/git/work/$2 -o /root/api/$1 #实际的生成文件的命令
cd /home/tomcat/apache-tomcat-8.5.8/bin # 进入tomcat的目录
./shutdown.sh #停止原服务
echo ======shutdown server end -rf /home/tomcat/apache-tomcat-8.5.8/webapps/$1 #删除tomcat下已经存在的接口文档文件
cp -rf /root/api/$1 /home/tomcat/apache-tomcat-8.5.8/webapps
# 复制新的接口文档文件
echo ======copy apidac end
./startup.sh #启动服务
echo ====== server start
4.执行脚本 ./apigen.sh 接口文档目录名 代码目录名
示例： ./apigen.sh book-api book
5.编辑代码更新脚本
cd /home/git/work/$1
echo ==== $1 ===check work
git pull
6. hotgen.sh，实现以上功能 "热点文档生成项目$1" # $1 为实际的项目名称
./codei.sh $1 #更新代码，必须保证仓库中存在代码
echo check code end
./apigen.sh $1-api $1 # 生成接口文档并且部署
示例：./hotgen.sh book

粘贴一张我的安装目录

 

遇到问题和待优化项
1. 无法实时检出项目
2. 脚本出问题，无法中断，会一直执行到底
刚开始测试的时候，建立很多空的新文件夹，名称为 -api 的，用 rm -rf 目录删除不掉，只能使用 rm -rf -- 目录名才能删除
3.有可能造成端口冲突，需要杀端口
待补充

 

 

参考的博客地址
apidoc
1. https://blog.csdn.net/chemphone/article/details/79193466 前半部分
2. https://www.cnblogs.com/minsons/articles/7154090.html 后半部分
linux 查看操作系统版本信息
https://www.cnblogs.com/vaelailai/p/7545166.html
3. 部署tomcat脚本文件