文章目录
- 一、概述
- 二、环境准备
- 三、接口文档生成
- 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#npm使用淘宝的镜像网址,否则安装特慢
npm config set registry http://registry.npm.taobao.org
#安装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
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 */)
doif [ -d "$dir"/.git ]; thenecho "$dir" && cd "$dir" && git pull && cd ..fi
doneecho "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.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
# defines variable
git="docker-demo" && path=`pwd` && gitpath=$path/$gitif [ ! -f $path/last ] ; thenecho "0">$path/last
fi# git clone then init
cd $gitpath && git pull && sh init.sh \
&& now=`git log -1 --format="%at"` \
&& last=`cat $path/last`# check timestamp, if changed print git log
if [ $now -gt $last ] ; thenecho "git changed!!" && echo $now>$path/last && echo `git log -1` \&& /usr/local/bin/apidoc -i $gitpath/src -o $path/doc \&& touch $path/doc
elseecho "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-