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

一、概述

最近忙于某开源项目的接口文档整理，采用了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
cd /work
git clone https://gitee.com/00fly/docker-demo.git

2. 初始化

cd /work/docker-demo
sh init.sh

执行后，会拷贝all-in-one.sh到上层目录

3.执行

cd /work/
sh all-in-one.sh

all-in-one.sh 实现了git更新与apidoc文档生成

#!/bin/sh
rm -rf docfor 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

四、文档发布

通过nginx发布

whereis nginx
cd /etc/nginx/conf.d
vi default.conf

修改内容为下图标红内容

重启nginx

nginx -t
nginx -s reload

五，配置定时运行

#查看
crontab -l#编辑
crontab -e

输入

* * * * * /bin/sh /work/all-in-one-cron.sh

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

#!/bin/sh
#download source by git clone
rm -rf /work/docker-demo && cd /work && /usr/bin/git clone https://gitee.com/00fly/docker-demo.git#move sh to parent directory
cd /work/docker-demo && sh init.sh#build apidoc
touch /work/doc
/usr/local/bin/apidoc -i /work/docker-demo/src -o /work/doc

六，docker运行

docker运行无需配置nodejs环境，apidoc运行环境在容器内，较方便

请参考 https://gitee.com/00fly/effict-side/tree/master/apidoc-image

---

有任何问题和建议，都可以向我提问讨论,大家一起进步，谢谢!

-over-