接口文档神器之apidoc

Posted 2020-11-03 源源猿

//@desn:apidoc linux环境  windows环境使用

//@desn:码字不宜，转载请注明出处

//@author:张慧源  <[e-mail]>

//@date:2018/5/6

 

正文：

windows版安装：

1.安装nodejs   （nodejs环境）

32 位安装包下载地址 : https://nodejs.org/dist/v4.4.3/node-v4.4.3-x86.msi

64 位安装包下载地址 : https://nodejs.org/dist/v4.4.3/node-v4.4.3-x64.msi

2.安装apidoc,

npm install -g apidoc

使用第一个命令版  运行上面的命令安装

 

linux版安装(ubuntu)

 

1、更新ubuntu软件源

sudo apt-get update 
sudo apt-get install -y python-software-properties software-properties-common 
sudo add-apt-repository ppa:chris-lea/node.js 
sudo apt-get update

2、安装nodejs

sudo apt-get install nodejs 
sudo apt install nodejs-legacy 
sudo apt install npm

3、更新npm包镜像源

sudo npm config set registry https://registry.npm.taobao.org 
sudo npm config list

4、全局安装n管理器（用于管理nodejs版本）

sudo npm install n -g

5、安装最新的nodejs（stable版本）

sudo n stable 
sudo node -v   （查看版本）

6、安装apidoc

sudo npm install apidoc -g

 

使用：以TP框架为例

在网站根目录放上模板  .json

 

内容：

{
"name": "example",
"version": "0.1.0",
"description": "A basic apiDoc example"
}

 

这里上个我代码里的注释（apidoc就是把注释转换为接口文档）

/**
 * @api {POST} http://aaa.com/index/Index/add_needs 添加用户需求
 * @apiVersion 1.0.0
 * @apiGroup NEED
 *
 * @apiParam {String} need_name 需求者名称-非空
 * @apiParam {String} e_mail 用户邮箱-非空邮箱格式
 * @apiParam  {String} phone 用户电话-非空
 * @apiParam {String} company_name 需求公司名称-非空
 * @apiParam  {String} needs_desc 需求描述-非空
 *
 * @apiSuccess {Object} code 返回码
 * @apiSuccess {Object} reason  中文解释
 * @apiSuccess {String[]} data  返回数据
 *
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *          "code":0,
 *          "reason":"需求已经提交了，我们的工作人员会在2个工作日内和您取得联系!",
 *          "data":[]
 *      }
 */

注释参考：http://apidocjs.com  （apidoc官网）

以TP为参考的重点：生成的docapi放在public下
命令：apidoc -i ./ -o ./public/apidoc   注：-i  应用目录 -o 输出apidoc位置   另命令要cd到应用根目录下运行

效果展示：