基于 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脚本文件

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

用apidoc 生成在线接口文档
在开发接口的过程中,需要向外发布相应的接口文档.开始的时候使用word来写文档,时间长了发现有几个问题.1) 编写不方便.每次新增借口的时候都要复制上一个接口,然后再进行修改,一些相同的部分无法复用, ...
SpringBoot集成swagger生成在线接口文档
SpringBoot集成swagger生成在线接口文档集成maven依赖 <dependency><groupId>io.springfox</groupId>& ...
vvv在线文档导出工具_使用ApiPost工具快速生成在线接口文档
ApiPost是一个支持团队协作,并可直接生成文档的API调试.管理工具.它支持模拟POST.GET.PUT等常见请求,是后台接口开发者或前端.接口测试人员不可多得的工具 .使用者不仅可以利用apio ...
Swagger2生成在线接口文档并导出pdf文件
文章目录一,配置 1,pom依赖 2,通用配置二,注解三,主题 1,默认主题效果 2,添加依赖 3,添加配置 4,启动看效果四,token验证方法1,所有接口上添加方法2,全局统一添加五 ...
python生成接口文档_使用apiDoc实现python接口文档编写
使用apiDoc实现python接口文档编写 apiDoc的安装 npm install apidoc -g 生成api的终端命令:apidoc -i 代码所在路径-o 生成文件的路径接口文档的编写 ...
Laravel使用Apidoc注解自动生成Api接口文档
本教程从零开始搭建laravel项目,并安装Apidoc扩展及使用注解生成Api接口文档的教程,该扩展支持多应用/版本.Markdown文档.在线接口调试.接口生成器.代码模板生成器.Mock调试数 ...
apidoc 自动化生成 api接口文档
手写api接口太麻烦. 学习了apidoc自动生成接口文档,这边做一下整理要用组件那就必须先安装 apidoc,做一下全局安装 npm install apidoc -g 新建配置文件apidoc. ...
自动生成python接口文档_Django自动生成Swagger接口文档
Django自动生成Swagger接口文档 1. 前言当接口开发完成,紧接着需要编写接口文档.传统的接口文档通常都是使用Word或者一些接口文档管理平台进行编写,但此类接口文档维护更新比较麻烦,每次 ...
Go之开发小功能集合（viper获取配置信息，test编写测试单元，用户目录获取，JWT安全校验，字符串去重，Swag在线接口文档，画字符图像工具，Gin模式的选择，iota枚举，promhttp等）
提示: 该链接是go语言小工具: https://www.kancloud.cn/congzaifeng/go_third_party_libraries/467593 Go语言学习全面文档:http ...

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

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

最新文章

热门文章

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

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

最新文章

热门文章

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

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