apidoc接口文档的自动更新与发布

02-28 1016阅读

文章目录

一、概述
二、环境准备
三、接口文档生成
- 1. 下载源码
- 2. 初始化
- 3.执行
- 四、文档发布
- 五，配置定时运行
- 六，docker运行
- 七，优化方向
  一、概述
  
  最近忙于某开源项目的接口文档整理，采用了apidoc来整理生成接口文档。
  apidoc是一个可以将源代码中的注释直接生成api接口文档的工具,对现有代码无侵入。他可以根据代码注释生成web api文档，支持大部分主流语言java javascript php coffeescript erlang perl python ruby go…，相对而言，web接口的注释维护起来更加方便，不需要额外再维护一份文档。
  
  下面我们以 docker-demo 项目为例来展示如何实现接口文档的自动更新与发布。
  效果如下：
  http://1.94.177.4
  
  二、环境准备
  
  云主机，centos7系统，安装组件：git、nodejs、npm、apidoc、nginx
  
  组件作用
  git 源码下载
  nodejs、npm apidoc环境
  apidoc 接口文档工具软件
  nginx 接口文档发布服务器
  安装git、nodejs、npm、apidoc
```
#安装git
yum install -y git
#安装apidoc之前要先安装node.js、npm
yum install -y nodejs
yum install -y npm
#安装apidoc
npm install -g apidoc
#验证
git --version
apidoc -v
apidoc -h
```
  配置nginx repo
```
vim /etc/yum.repos.d/nginx.repo
[nginx-stable]
name=nginx stable repo
baseurl=http://nginx.org/packages/centos/$releasever/$basearch/
gpgcheck=1
enabled=1
gpgkey=https://nginx.org/keys/nginx_signing.key
module_hotfixes=true
[nginx-mainline]
name=nginx mainline repo
baseurl=http://nginx.org/packages/mainline/centos/$releasever/$basearch/
gpgcheck=1
enabled=0
gpgkey=https://nginx.org/keys/nginx_signing.key
module_hotfixes=true
```
  安装nginx
```
#查看yum的nginx信息
yum info nginx
#执行命令安装
yum -y install nginx
#查看安装目录
whereis nginx
#设为开机启动
sudo systemctl enable nginx.service
启动/停止/重启/查看状态  nginx
sudo systemctl start   nginx.service
sudo systemctl stop    nginx.service
sudo systemctl restart nginx.service
sudo systemctl status  nginx.service
```
  三、接口文档生成
  
  1. 下载源码
  
  使用git下载
```
mkdir /work/gitee && cd /work/gitee
git clone https://gitee.com/00fly/docker-demo.git && touch last-update-time
```
  2. 初始化
```
cd /work/gitee/docker-demo
sh init.sh
```
  执行后，会拷贝all-in-one.sh到上层目录
  
  3.执行
```
cd /work/gitee
sh all-in-one.sh
```
  all-in-one.sh 实现了git更新与apidoc文档生成
```
#!/bin/sh
for dir in $(ls -d */)
do
  if [ -d "$dir"/.git ]; then
    echo "$dir" && cd "$dir" && git pull && cd ..
  fi
done
echo "Will Run: apidoc -i  docker-demo/src -o doc"
apidoc -i  docker-demo/src -o doc && touch doc
```
  文件结构如下：
  
  四、文档发布
  
  通过nginx发布
```
whereis nginx
cd /etc/nginx/conf.d
vi default.conf
```
  修改内容为下图标红内容
  
  
  重启nginx
```
nginx -t
nginx -s reload
```
  五，配置定时运行
```
#查看
crontab -l
#编辑
crontab -e
```
  输入
```
* * * * * cd /work/gitee&&sh all-in-one-cron.sh
```
  注意：直接写为* * * * * /work/gitee/all-in-one-cron-push.sh，crontab执行pwd结果为/root
  
  crontab 实现了每分钟生成接口文档，具体可下拉文档到最后，看时间戳内容,e.g:
  构建于 apidoc 1.2.0 - Sat Feb 24 2024 17:26:01 GMT+0800 (China Standard Time)
  
  crontab中定义的shell必须使用全路径
  
  all-in-one-cron.sh 已经实现：计算最近一次git提交的时间与本地更新时间差(单位：秒), 如果时间差大于0则打印git提交日志并执行apidoc
```
#!/bin/sh
# define var
git="docker-demo" && path=`pwd` && gitpath=$path/$git
# git clone then init
cd $gitpath && /usr/bin/git pull && touch $gitpath && sh init.sh
 
# check timestamp, if changed print git log and build apidoc
((t = `/usr/bin/git log -1 --format="%at"` - `date +%s -r $path/last-update-time`))
if [ $t -gt 0 ] ; then
  echo "git changed!!" && touch $path/last-update-time \
  && cd $gitpath && echo `/usr/bin/git log -1` \
  && /usr/local/bin/apidoc -i $gitpath/src -o $path/doc && touch $path/doc
else
  echo "git not change"
fi
```
  六，docker运行
  
  docker运行无需配置nodejs环境，apidoc运行环境在容器内，较方便
  
  请参考 https://gitee.com/00fly/effict-side/tree/master/apidoc-image
  
  七，优化方向
  
  使用crontab来定时更新接口文档，大部分是无效工作，因为接口文档的源文件并未变化。最新all-in-one-cron.sh已经解决此问题。
  
  考虑使用jenkins来集成。
  大致流程为：
  
  具体流程就不再详细阐述了，留着各位大佬自己研究实现！
  
  有任何问题和建议，都可以向我提问讨论,大家一起进步，谢谢!
  
  -over-