Web API 文档生成工具 apidoc

sushi 发布于2019-08-15 13:47 / 1086人阅读

摘要：实现接口文档编写工作，有很多种方式，例如通过文档编写，或者通过进行维护。这里，笔者想分享另一个文档生成工具。此外，可以支持多种语言，，，，，，。查询签收预警策略查询签收预警策略平台类型商家名称最后，我们在终端输入命令进行文档生成。

原文地址：梁桂钊的博客

在服务端开发过程中，我们需要提供一份 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 命名进行安装。

npm install apidoc -g

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

{
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "title": "Custom apiDoc browser title",
  "url" : "https://api.github.com/v1"
}

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

/**
 *   @api {GET} logistics/policys 查询签收预警策略
 *   @apiDescription 查询签收预警策略
 *   @apiGroup QUERY
 *   @apiName logistics/policys
 *   @apiParam  {Integer} edition   平台类型
 *   @apiParam  {String} tenantCode 商家名称
 *   @apiPermission LOGISTICS_POCILY
 */

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

apidoc -i myapp/ -o apidoc/

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

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

代码注释 @api

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

@api {method} path [title]

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

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

@apiDescription

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

@apiDescription text

@apiGroup

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

@apiGroup name

@apiName

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

@apiName name

@apiVersion

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

@apiVersion version

@apiParam

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

@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 接口需要的响应错误。

这里，我们看一个案例。

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

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

@apiPermission

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

@apiPermission name

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

完整的案例

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

首先，配置 apidoc.json，内容如下：

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

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

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

然后，执行命名生成文档。

apidoc -i myapp/ -o apidoc/

生成的页面，如下所示。

（完）

更多精彩文章，尽在「服务端思维」微信公众号！

云服务器 GPU云服务器生成API文档接口文档生成工具 api文档工具 api接口文档工具

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/68309.html

开源的api文档管理系统

摘要：国外的话国内的国内开源的非常好用的一款文档管理系统，安装也非常方便，只需将源代码放到项目目录下自动安装运行即可，不要要注意版本必须大于界面简洁功能强大的阿里的接口管理工具，开源免费，接口自动化，数据自动生成，自动化测试，企业级管理。在项目中，需要协同开发，所以会写许多API文档给其他同事，以前都是写一个简单的TXT文本或Word文档，口口相传，这种方式比较老土了，所以，需要有个api...

zsirfs 2019-06-27 14:58 评论0 收藏0
ApiDoc + github page 使用

摘要：目前支持的变成语言有，，，等，主流的编成语言都支持。文件时你要生成文档的目录，也是最后要使用的目录。是一项免费的服务，它允许你把你的静态页面发布出去共其他用户通过浏览器查看。你的项目在用什么工具书写api文档？今天就来给大家推荐下ApiDoc 1. ApiDoc是什么？ ApiDoc可以根据你再代码里的注释，来生成api描述文档，这样就不用你自己去告诉端的小伙伴该怎么调用你的api了...

Joonas 2019-08-23 13:42 评论0 收藏0
ApiDoc + github page 使用

摘要：目前支持的变成语言有，，，等，主流的编成语言都支持。文件时你要生成文档的目录，也是最后要使用的目录。是一项免费的服务，它允许你把你的静态页面发布出去共其他用户通过浏览器查看。你的项目在用什么工具书写api文档？今天就来给大家推荐下ApiDoc 1. ApiDoc是什么？ ApiDoc可以根据你再代码里的注释，来生成api描述文档，这样就不用你自己去告诉端的小伙伴该怎么调用你的api了...

luodongseu 2019-08-02 12:07 评论0 收藏0
ApiDoc + github page 使用

摘要：目前支持的变成语言有，，，等，主流的编成语言都支持。文件时你要生成文档的目录，也是最后要使用的目录。是一项免费的服务，它允许你把你的静态页面发布出去共其他用户通过浏览器查看。你的项目在用什么工具书写api文档？今天就来给大家推荐下ApiDoc 1. ApiDoc是什么？ ApiDoc可以根据你再代码里的注释，来生成api描述文档，这样就不用你自己去告诉端的小伙伴该怎么调用你的api了...

ytwman 2019-08-16 13:50 评论0 收藏0