数据API 案例 开发者 关于
掌握聚合最新动态了解行业最新趋势
API接口,开发服务,免费咨询服务
新闻动态 > 媒体报道

Web API 文档生成工具 apidoc使用指南

在服务端开发过程中,我们需要提供一份 API 接口文档给 Web 端和移动端使用。实现 API 接口文档编写工作,有很多种方式,例如通过 Word 文档编写,或者通过 MediaWiki 进行维护。此外,还有比较流行的方式是利用 Swagger 自动化生成文档。这里,笔者想分享另一个 Web API 文档生成工具 apidoc。

apidoc 是通过源码中的注释来生成 Web API 文档。因此,apidoc 对现有代码可以做到无侵入性。此外,apidoc 可以支持多种语言 C#, Go, Dart, Java, JavaScript, PHP, TypeScript (all DocStyle capable languages),CoffeeScript,Erlang,Perl,Python,Ruby,Lua。通过 apidoc 可以非常方便地生成可交互地文档页面。

开始入门

首先,我们需要 node.js 的支持。在搭建好 node.js 环境后,通过终端输入 npm 命名进行安装。

  1. npm install apidoc -g

接着,我们还需要添加 apidoc.json 文件到项目工程的根目录下。

  1. {
  2. "name": "example",
  3. "version": "0.1.0",
  4. "description": "apiDoc basic example",
  5. "title": "Custom apiDoc browser title",
  6. "url" : "https://api.github.com/v1"
  7. }

这里,笔者主要演示 Java 注释如何和 apidoc 结合使用。现在,我们先来看一个案例。

  1. /**
  2. * @api {GET} logistics/policys 查询签收预警策略
  3. * @apiDescription 查询签收预警策略
  4. * @apiGroup QUERY
  5. * @apiName logistics/policys
  6. * @apiParam {Integer} edition 平台类型
  7. * @apiParam {String} tenantCode 商家名称
  8. * @apiPermission LOGISTICS_POCILY
  9. */

最后,我们在终端输入 apidoc 命令进行文档生成。这里,我们用自己的项目工程的根目录替代 myapp/,用需要生成文档的地址替代 apidoc/。

  1. apidoc -i myapp/ -o apidoc/

例如,笔者的配置是这样的。

  1. apidoc -i /Users/lianggzone/Documents/dev-space/git-repo -o /Users/lianggzone/Documents/dev-space/apidoc/

代码注释

@api

@api 标签是必填的,只有使用 @api 标签的注释块才会被解析生成文档内容。格式如下:

  1. @api {method} path [title]

这里,有必要对参数内容进行讲解。

参数名描述
method请求方法, 如 POST,GET,POST,PUT,DELETE 等。
path请求路径。
title【选填】简单的描述

@apiDescription

@apiDescription 对 API 接口进行描述。格式如下:

  1. @apiDescription text

@apiGroup

@apiGroup 表示分组名称,它会被解析成一级导航栏菜单。格式如下:

  1. @apiGroup name

@apiName

@apiName 表示接口名称。注意的是,在同一个 @apiGroup 下,名称相同的 @api 通过 @apiVersion 区分,否者后面 @api 会覆盖前面定义的 @api。格式如下:

  1. @apiName name

@apiVersion

@apiVersion 表示接口的版本,和 @apiName 一起使用。格式如下:

  1. @apiVersion version

@apiParam

@apiParam 定义 API 接口需要的请求参数。格式如下:

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

这里,有必要对参数内容进行讲解。

参数名描述
(group)【选填】参数进行分组
{type}【选填】参数类型,包括{Boolean}, {Number}, {String}, {Object}, {String[]}, (array of strings), …
{type{size}}【选填】可以声明参数范围,例如{string{..5}}, {string{2..5}}, {number{100-999}}
{type=allowedValues}【选填】可以声明参数允许的枚举值,例如{string="small","huge"}, {number=1,2,3,99}
field参数名称
[field]声明该参数可选
=defaultValue【选填】声明该参数默认值
description【选填】声明该参数描述
:—:—

类似的用法,还有 @apiHeader 定义 API 接口需要的请求头,@apiSuccess 定义 API 接口需要的响应成功,@apiError 定义了 API 接口需要的响应错误。

这里,我们看一个案例。

  1. /**
  2. * @apiParam {Integer} edition=1 平台类型
  3. * @apiParam {String} [tenantCode] 商家名称
  4. */

此外,还有 @apiParamExample,@apiHeaderExample, @apiErrorExample,@apiSuccessExample 可以用来在文档中提供相关示例。

@apiPermission

@apiPermission 定义 API 接口需要的权限点。格式如下:

  1. @apiPermission name

此外,还有一些特别的注解。例如 @apiDeprecated 表示这个 API 接口已经废弃,@apiIgnore 表示忽略这个接口的解析。关于更多的使用细节,可以阅读官方文档:http://apidocjs.com/#demo

完整的案例

最后,我们用官方的案例,讲解下一个完整的配置。

首先,配置 apidoc.json,内容如下:

  1. {
  2. "name": "example",
  3. "version": "0.1.0",
  4. "description": "A basic apiDoc example"
  5. }

接着,我们配置相关的 Java 源码注释。

  1. /**
  2. * @api {get} /user/:id Request User information
  3. * @apiName GetUser
  4. * @apiGroup User
  5. *
  6. * @apiParam {Number} id Users unique ID.
  7. *
  8. * @apiSuccess {String} firstname Firstname of the User.
  9. * @apiSuccess {String} lastname Lastname of the User.
  10. *
  11. 标签/Tag

掌握聚合最新动态了解行业最新趋势
API接口,开发服务,免费咨询服务
新闻动态 > 媒体报道
Web API 文档生成工具 apidoc使用指南
发布:2018-01-23

在服务端开发过程中,我们需要提供一份 API 接口文档给 Web 端和移动端使用。实现 API 接口文档编写工作,有很多种方式,例如通过 Word 文档编写,或者通过 MediaWiki 进行维护。此外,还有比较流行的方式是利用 Swagger 自动化生成文档。这里,笔者想分享另一个 Web API 文档生成工具 apidoc。

apidoc 是通过源码中的注释来生成 Web API 文档。因此,apidoc 对现有代码可以做到无侵入性。此外,apidoc 可以支持多种语言 C#, Go, Dart, Java, JavaScript, PHP, TypeScript (all DocStyle capable languages),CoffeeScript,Erlang,Perl,Python,Ruby,Lua。通过 apidoc 可以非常方便地生成可交互地文档页面。

开始入门

首先,我们需要 node.js 的支持。在搭建好 node.js 环境后,通过终端输入 npm 命名进行安装。

  1. npm install apidoc -g

接着,我们还需要添加 apidoc.json 文件到项目工程的根目录下。

  1. {
  2. "name": "example",
  3. "version": "0.1.0",
  4. "description": "apiDoc basic example",
  5. "title": "Custom apiDoc browser title",
  6. "url" : "https://api.github.com/v1"
  7. }

这里,笔者主要演示 Java 注释如何和 apidoc 结合使用。现在,我们先来看一个案例。

  1. /**
  2. * @api {GET} logistics/policys 查询签收预警策略
  3. * @apiDescription 查询签收预警策略
  4. * @apiGroup QUERY
  5. * @apiName logistics/policys
  6. * @apiParam {Integer} edition 平台类型
  7. * @apiParam {String} tenantCode 商家名称
  8. * @apiPermission LOGISTICS_POCILY
  9. */

最后,我们在终端输入 apidoc 命令进行文档生成。这里,我们用自己的项目工程的根目录替代 myapp/,用需要生成文档的地址替代 apidoc/。

  1. apidoc -i myapp/ -o apidoc/

例如,笔者的配置是这样的。

  1. apidoc -i /Users/lianggzone/Documents/dev-space/git-repo -o /Users/lianggzone/Documents/dev-space/apidoc/

代码注释

@api

@api 标签是必填的,只有使用 @api 标签的注释块才会被解析生成文档内容。格式如下:

  1. @api {method} path [title]

这里,有必要对参数内容进行讲解。

参数名描述
method请求方法, 如 POST,GET,POST,PUT,DELETE 等。
path请求路径。
title【选填】简单的描述

@apiDescription

@apiDescription 对 API 接口进行描述。格式如下:

  1. @apiDescription text

@apiGroup

@apiGroup 表示分组名称,它会被解析成一级导航栏菜单。格式如下:

  1. @apiGroup name

@apiName

@apiName 表示接口名称。注意的是,在同一个 @apiGroup 下,名称相同的 @api 通过 @apiVersion 区分,否者后面 @api 会覆盖前面定义的 @api。格式如下:

  1. @apiName name

@apiVersion

@apiVersion 表示接口的版本,和 @apiName 一起使用。格式如下:

  1. @apiVersion version

@apiParam

@apiParam 定义 API 接口需要的请求参数。格式如下:

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

这里,有必要对参数内容进行讲解。

参数名描述
(group)【选填】参数进行分组
{type}【选填】参数类型,包括{Boolean}, {Number}, {String}, {Object}, {String[]}, (array of strings), …
{type{size}}【选填】可以声明参数范围,例如{string{..5}}, {string{2..5}}, {number{100-999}}
{type=allowedValues}【选填】可以声明参数允许的枚举值,例如{string="small","huge"}, {number=1,2,3,99}
field参数名称
[field]声明该参数可选
=defaultValue【选填】声明该参数默认值
description【选填】声明该参数描述
:—:—

类似的用法,还有 @apiHeader 定义 API 接口需要的请求头,@apiSuccess 定义 API 接口需要的响应成功,@apiError 定义了 API 接口需要的响应错误。

这里,我们看一个案例。

  1. /**
  2. * @apiParam {Integer} edition=1 平台类型
  3. * @apiParam {String} [tenantCode] 商家名称
  4. */

此外,还有 @apiParamExample,@apiHeaderExample, @apiErrorExample,@apiSuccessExample 可以用来在文档中提供相关示例。

@apiPermission

@apiPermission 定义 API 接口需要的权限点。格式如下:

  1. @apiPermission name

此外,还有一些特别的注解。例如 @apiDeprecated 表示这个 API 接口已经废弃,@apiIgnore 表示忽略这个接口的解析。关于更多的使用细节,可以阅读官方文档:http://apidocjs.com/#demo

完整的案例

最后,我们用官方的案例,讲解下一个完整的配置。

首先,配置 apidoc.json,内容如下:

  1. {
  2. "name": "example",
  3. "version": "0.1.0",
  4. "description": "A basic apiDoc example"
  5. }

接着,我们配置相关的 Java 源码注释。

  1. /**
  2. * @api {get} /user/:id Request User information
  3. * @apiName GetUser
  4. * @apiGroup User
  5. *
  6. * @apiParam {Number} id Users unique ID.
  7. *
  8. * @apiSuccess {String} firstname Firstname of the User.
  9. * @apiSuccess {String} lastname Lastname of the User.
  10. *
  11. 电话 0512-88869195