道者编程


API文档自动生成工具apiDoc

一:介绍

apidoc 是一个基于 nodejs 的 API 文档生成工具,从代码注释中提取特定格式的内容,生成 API 文档。程序员都不喜欢写文档,但是程序员习惯写注释。可谓一举两得。

apidoc目前支持php,python,java,go,rust,perl,c#等等几乎主流语言都支持。

二:安装

1:首先安装nodejs

下载地址:https://nodejs.org/en/download/

安装完成后,查看一下:


2:全局安装 apidoc

npm  install apidoc -g

3:查看是否安装成功

apidoc -v
 

三:小试身手

1:新建一个项目目录abc:E:\www\abc,在该目录下新建3个文件

(1):apidoc.json

{
  "name": "测试API",
  "version": "1.0.0",
  "description": "测试API",
  "title": "测试API",
   "url" : "https://127.0.0.1:90/v1",
  "header": {
    "title": "测试APId",
    "filename": "header.md"
  },
  "footer": {
    "title": "测试API",
    "filename": "footer.md"
  }
}
 (2):header.md

header
 (3):footer.md

footer


2:在abc目录下新建一个src目录,该目录保存程序


3:src下新建两个文件,执行的时候apidoc从这两个文件提取

(1):articles.php

 
<?php

/**
 * @api {get} /articles/:id 根据单个id获取文章信息
 * @apiName 根据id获取文章信息
 * @apiGroup Articles
 *
 * @apiParam (params) {String} id       文章id
 *
 * @apiSuccess {Array} article 返回相应id的文章信息
 *
 * @apiSuccessExample Success-Response:
 *    HTTP/1.1 200 OK
 *      {
 *        "tile": "文章标题2",
 *        "date": 1483941498230,
 *        "author": "classlfz",
 *        "content": "文章的详细内容"
 *       }
 *
 * @apiError (Error 4xx) 404 对应id的文章信息不存在
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 对应id的文章信息不存在
 *     {
 *       "error": err
 *     }
 */

(2):user.php

<?php


/**
 * @api {post} /user/ 查询用户
 * @apiName 根据查询条件返回用户信息
 * @apiGroup User

 * @apiParam {String} [firstname]  Optional Firstname of the User.
 * @apiParam {String} lastname     Mandatory Lastname.
 * @apiParam {String} country="DE" Mandatory with default value "DE".
 * @apiParam {Number} [age=18]     Optional Age with default 18.
 *
 * @apiParam (Login) {String} pass Only logged in users can post this.
 *                                 In generated documentation a separate
 *                                 "Login" Block will be generated.
 */

 

4:运行,首先进入abc目录

apidoc -i src/ -o apidoc/
 以上表示提取src/里面的数据,生成到apidoc目录下


这样表示成功,打开看下


直接浏览器打开apiddoc中的index.html。


然后把nginx或者apache绑定到这个目录即可!

参数说明:
-f 文件类型
-i 文件输入路径(必选)
- o 输出路径(必选)
- t 使用模板(非必选,一般不用)

apidoc -f .php -i src/ -o apidoc/

这句话意思是:把src目录下的.php文件 api输出到apidoc目录下(运行该命令,需要在apidoc.json同级目录下)

三:基本规则:

以下转自:https://www.jianshu.com/p/a799c23234b8

@api

@api一般是必须编写的(除非你是用了@apiDefine),不然apidoc编译器会忽略这段注释。

/** 
 * @api {method} path [title]
 */
NameDescription
method请求的方法名称:如GETPOST等等
path请求路径
title(可选)一个简短的标题(用于导航跟文档标题)

@apiGroup

定于api归属的组名,生成的文档会把该api注释归类到该值对应的api组上。

/**
 * @apiGroup name
 */
NameDescription
name组名称

@apiName

@apiName用于定义API文档的一个实例,并用作实例名称 。

/**
 * @apiName name
 */
NameDescription
name实例名称

@apiParam

@apiParam用于编写API的参数以及参数的解释。

/**
 * @apiParam [(group)] [{type}] [field=defaultValue] [description]
 */
NameDescription
(group) 可选参数归属组名,不填写组名,则默认设为Paramter
{type} 可选参数数据类型,如{String}{Number}{Array}等等
{type{size}} 可选变量的大小信息 {String{..5}}参数类型为一个字符不超过5的字符串;{String{2..5}}参数为一个字符在2到5之间的字符串;
{type=allowedValues} 可选参数允许值 {string="small","huge"}参数只能接受small或者huge的字符串
field 可选参数名称
=defaultValue参数默认值
description(可选)描述

@apiParamExample

@apiParamExample参数例子

/**
 * @apiParamExample [{type}] [title]
 *    example
 */
NameDescription
{type} 可选请求数据结构
title 可选例子的一个简短的标题
example例子的详细信息,可多个例子并存

@apiSuccess

请求成功后的返回字段参数

/**
 * @apiSuccess [(group)] [{type}] field [description]
 */
NameDescription
(group) 可选参数归属组名,不填写组名,则默认设为Success 200
{type} 可选返回的数据类型,如{String}{Number}等等
field返回的标示符(返回成功的状态码)
description 可选描述

@apiSuccessExample

请求成功后返回的字段参数例子

/**
 * @apiSuccessExample [{type}] [title] example
 */
NameDescription
{type} 可选请求数据结构
title 可选例子的一个简短的标题
example例子的详细信息,可多个例子并存

@apiError & @apiErrorExample

这个的用法跟@apiSuccess@apiSuccessExample的用法相类似。

更多用法参考官网:http://apidocjs.com/


最新评论:
1楼 广东省深圳市 电信 发表于 2018-06-11 17:58:34
66666666666
共有 1 条记录  首页 上一页 下一页 尾页 1
我要评论:

看不清楚


道知

about me

身体是革命的本钱,健身,养生,运动,公众号都有!

链接