模板建网站价格,做网站的三年规划,宿州大型网站建设公司,WordPress织梦哪个快文章目录 一、概述二、环境准备三、接口文档生成1. 下载源码2. 初始化3.执行 四、文档发布五#xff0c;配置定时运行六#xff0c;docker运行七#xff0c;不足与优化分析 一、概述
最近忙于某开源项目的接口文档整理#xff0c;采用了apidoc来整理生成接口文档。 apidoc… 文章目录 一、概述二、环境准备三、接口文档生成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、npmapidoc环境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]
namenginx stable repo
baseurlhttp://nginx.org/packages/centos/$releasever/$basearch/
gpgcheck1
enabled1
gpgkeyhttps://nginx.org/keys/nginx_signing.key
module_hotfixestrue[nginx-mainline]
namenginx mainline repo
baseurlhttp://nginx.org/packages/mainline/centos/$releasever/$basearch/
gpgcheck1
enabled0
gpgkeyhttps://nginx.org/keys/nginx_signing.key
module_hotfixestrue安装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.git2. 初始化
cd /work/docker-demo
sh init.sh执行后会拷贝all-in-one.sh到上层目录
3.执行
cd /work/
sh all-in-one.shall-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.shcrontab 实现了每分钟生成接口文档具体可下拉文档到最后看时间戳内容,e.g: 构建于 apidoc 1.2.0 - Sat Feb 24 2024 17:26:01 GMT0800 (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
/usr/local/bin/apidoc -i /work/docker-demo/src -o /work/doc
touch /work/doc六docker运行
docker运行无需配置nodejs环境apidoc运行环境在容器内较方便
请参考 https://gitee.com/00fly/effict-side/tree/master/apidoc-image
七不足与优化分析
使用crontab来定时更新接口文档大部分是无效工作因为接口文档的源文件并未变化。 可以考虑使用jenkins来集成。 大致流程为 #mermaid-svg-74hn8uxeGhdS2zuo {font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}#mermaid-svg-74hn8uxeGhdS2zuo .error-icon{fill:#552222;}#mermaid-svg-74hn8uxeGhdS2zuo .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-74hn8uxeGhdS2zuo .edge-thickness-normal{stroke-width:2px;}#mermaid-svg-74hn8uxeGhdS2zuo .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-74hn8uxeGhdS2zuo .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-74hn8uxeGhdS2zuo .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-74hn8uxeGhdS2zuo .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-74hn8uxeGhdS2zuo .marker{fill:#333333;stroke:#333333;}#mermaid-svg-74hn8uxeGhdS2zuo .marker.cross{stroke:#333333;}#mermaid-svg-74hn8uxeGhdS2zuo svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-74hn8uxeGhdS2zuo .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-74hn8uxeGhdS2zuo .cluster-label text{fill:#333;}#mermaid-svg-74hn8uxeGhdS2zuo .cluster-label span{color:#333;}#mermaid-svg-74hn8uxeGhdS2zuo .label text,#mermaid-svg-74hn8uxeGhdS2zuo span{fill:#333;color:#333;}#mermaid-svg-74hn8uxeGhdS2zuo .node rect,#mermaid-svg-74hn8uxeGhdS2zuo .node circle,#mermaid-svg-74hn8uxeGhdS2zuo .node ellipse,#mermaid-svg-74hn8uxeGhdS2zuo .node polygon,#mermaid-svg-74hn8uxeGhdS2zuo .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-74hn8uxeGhdS2zuo .node .label{text-align:center;}#mermaid-svg-74hn8uxeGhdS2zuo .node.clickable{cursor:pointer;}#mermaid-svg-74hn8uxeGhdS2zuo .arrowheadPath{fill:#333333;}#mermaid-svg-74hn8uxeGhdS2zuo .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-74hn8uxeGhdS2zuo .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-74hn8uxeGhdS2zuo .edgeLabel{background-color:#e8e8e8;text-align:center;}#mermaid-svg-74hn8uxeGhdS2zuo .edgeLabel rect{opacity:0.5;background-color:#e8e8e8;fill:#e8e8e8;}#mermaid-svg-74hn8uxeGhdS2zuo .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-74hn8uxeGhdS2zuo .cluster text{fill:#333;}#mermaid-svg-74hn8uxeGhdS2zuo .cluster span{color:#333;}#mermaid-svg-74hn8uxeGhdS2zuo div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-74hn8uxeGhdS2zuo :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 配置项目git源码地址 周期性检查源码是否更新 调用apidoc脚本生成接口文档 接口文档打包上传到nginx服务器 具体流程就不再详细阐述了留着各位大佬自己研究实现 有任何问题和建议都可以向我提问讨论,大家一起进步谢谢!
-over-
