apidoc 生成Restful web Api文档

时间：2022-05-09 14:48:08

在服务器项目开发过程中，总会牵扯到接口文档的设计与编写，之前使用的都是office写一个文档，不够直观。下面介绍一种工具生成Apidoc.,
该工具是Nodejs的模块，请务必在使用前安装好nodejs环境！

一．安装Apidoc

1.安装nmp环境,Windows环境可直接通过http://nodejs.org/下载安装包安装

2.安装后在cmd终端执行npm install apidoc –g如果执行失败跳到步骤3

3.安装npm首先先安装Homebrew在终端ruby -e "$(curl –fsSL

https://raw.githubusercontent.com/Homebrew/install/master/install)"

4.执行成功终端输入brew install node等待一段时间

5.执行成功终端输入npm –v确认是否npm安装成功

apidoc 生成Restful web Api文档

6.安装npm成功后执行执行npm install apidoc –g 安装apidoc即可。

二．apidoc使用

1.在项目根目录中创建apidoc.json文件

{

"name": "Apidoc merchant",

"version": "1.0.0",

"description": "智慧式车位锁Apidoc",

"title": "智慧式车位锁Apidoc",

"url" : "http://192.168.2.216:8080",

"sampleUrl": "http://192.168.2.216:8080",

"forceLanguage":"zh-cn",

"template": {

"withCompare": true,

"withGenerator": true

}

　　

2.在对应接口上加上注释:

示例:

/**

 * 查找代理Agent

 *

 * @return

 */

/**

 *

 * @api {post} /agent/findLi  获取代理列表

 * @apiName 获取代理列表

 * @apiGroup agent 代理

 * @apiVersion 1.0.0

 * @apiDescription 获取代理列表

 *

 * @apiParam {int} currentPage 当前页

 * @apiParam {int} pageSize 查询条数

 *

 * @apiSuccess {int} code 结果码 0：成功 1：失败

 * @apiSuccess {Object} msg 消息说明

 * @apiSuccessExample Success-Response:

 *  HTTP/1.1 200 OK

 * {

 * code:0,

 * desc:'',

 * data:{}

 *  }

 *

 *  @apiError All 对应<code>code</code>请求错误

 *  @apiErrorExample {json} Error-Response:

 *  HTTP/1.1 200

 *  {

 *   code:-1,

 *   desc:'',

 *   }

 */

@RequestMapping(value = "/findLi", method = RequestMethod.POST)

@ResponseBody

public BaseReturn<Page<Agent>> findLi(@RequestParam int currentPage, @RequestParam int pageSize, Integer status) {

    List<Criterion> criterias = new ArrayList<Criterion>();

    if (status != null)

        criterias.add(Restrictions.eq("status", status));

    Page<Agent> page = agentService.findLi(currentPage, pageSize, criterias);

    BaseReturn<Page<Agent>> baseReturn = new BaseReturn<Page<Agent>>();

    baseReturn.setData(page);

    baseReturn.setCode(BaseReturn.SUCCESSFULTAG);

    return baseReturn;

}

3.执行终端命令apidoc -i example/ -o doc/执行成功就则会在该目录下生成doc文件。

// 典型用法

apidoc -i api/ -o doc/api [-c ./] -f ".*\.js$"

-i 表示输入，后面是文件夹路径

-o 表示输出，后面是文件夹路径

默认会带上-c，在当前路径下寻找配置文件(apidoc.json)，如果找不到则会在package.json中寻找 "apidoc": { }

-f 为文件过滤，后面是正则表达式，示例为只选着js文件

  与-f类似，还有一个 -e 的选项，表示要排除的文件/文件夹，也是使用正则表达式

示例:

apidoc -i C:\Users\zhs_0\Desktop\merchant -o C:\Users\zhs_0\Desktop\merchant\src\main\webapp\pages\doc

这样就会在C:\Users\zhs_0\Desktop\merchant\src\main\webapp\pages\doc目录下生成项目的doc文档,点开index.html就会看到如下效果

apidoc 生成Restful web Api文档

三．apidoc代码注释

apidoc支持如下关键字

@api {method} path [title]

  只有使用@api标注的注释块才会在解析之后生成文档，title会被解析为导航菜单(@apiGroup)下的小菜单

  method可以有空格，如{POST GET}

@apiGroup name

  分组名称，被解析为导航栏菜单

@apiName name

  接口名称，在同一个@apiGroup下，名称相同的@api通过@apiVersion区分，否者后面@api会覆盖前面定义的@api

@apiDescription text

  接口描述，支持html语法

@apiVersion verison

  接口版本，major.minor.patch的形式

@apiIgnore [hint]

  apidoc会忽略使用@apiIgnore标注的接口，hint为描述

@apiSampleRequest url

  接口测试地址以供测试，发送请求时，@api method必须为POST/GET等其中一种

@apiDefine name [title] [description]

  定义一个注释块(不包含@api)，配合@apiUse使用可以引入注释块

  在@apiDefine内部不可以使用@apiUse

@apiUse name

  引入一个@apiDefine的注释块

@apiParam [(group)] [{type}] [field=defaultValue] [description]

@apiHeader [(group)] [{type}] [field=defaultValue] [description]

@apiError [(group)] [{type}] field [description]

@apiSuccess [(group)] [{type}] field [description]

  用法基本类似，分别描述请求参数、头部，响应错误和成功

  group表示参数的分组，type表示类型(不能有空格)，入参可以定义默认值(不能有空格)

@apiParamExample [{type}] [title] example

@apiHeaderExample [{type}] [title] example

@apiErrorExample [{type}] [title] example

@apiSuccessExample [{type}] [title] example

  用法完全一致，但是type表示的是example的语言类型

  example书写成什么样就会解析成什么样，所以最好是书写的时候注意格式化，(许多编辑器都有列模式，可以使用列模式快速对代码添加*号)

@apiPermission name

  name必须独一无二，描述@api的访问权限，如admin/anyone

详细文档参考http://caixw.oschina.io/apido

相关文章