数据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. 声明:所有来源为“聚合数据”的内容信息,未经本网许可,不得转载!如对内容有异议或投诉,请与我们联系。邮箱:marketing@think-land.com

掌握聚合最新动态了解行业最新趋势
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. 声明:所有来源为“聚合数据”的内容信息,未经本网许可,不得转载!如对内容有异议或投诉,请与我们联系。邮箱:marketing@think-land.com

选择想要的接口, 看看能免费获取多少次调用 选择(单选)或填写想要的接口
  • 短信API服务
  • 银行卡四元素检测[简]
  • 身份证实名认证
  • 手机状态查询
  • 三网手机实名制认证[简]
  • 身份证OCR识别
  • 风险信息查询
  • 企业工商信息
短信API服务
  • 短信API服务
  • 银行卡四元素检测[简]
  • 身份证实名认证
  • 手机状态查询
  • 三网手机实名制认证[简]
  • 身份证OCR识别
  • 风险信息查询
  • 企业工商信息
  • 确定
选择您的身份
请选择寻找接口的目的
预计每月调用量
请选择预计每月调用量
产品研发的阶段
请选择产品研发的阶段
×
企业用户认证,
可获得1000次免费调用
注册登录 > 企业账户认证 > 领取接口包
企业用户认证领取接口包 立即领取
× 企业用户认证,
可获得1000次免费调用,立即领取>
数 据 驱 动 未 来
Data Drives The Future