APIDOC

Inline Docmentation for RESTful web APIs

官网地址:http://apidocjs.com/#getting-started

apiDoc通过源代码里面的API注解生成一份文档

/** 
* @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. 
*/

官方例子: watch Demo output

前言

 文档中所有的例子都使用Javadoc风格(适用于C#,Go,Dart,Java,JavaScript, PHP, TypeScript)

  /** 
    * This is a comment. 
    */

安装

npm install apidoc -g

运行

apidoc -i myproject/ -o mydoc/ -t mytemplate/

通过mytemplate文件夹下的模板文件,把myproject文件夹下的所有文件的注释内容生成api文档,并放在mydoc文件夹下.

终端命令行

提示帮助

apidoc -h

参数	描述
-f	通过正则筛选哪些文件需要生成文档的.(默认: .cs .dart .erl .go .java .js .php .py .rb .ts )
-i	你的项目文件所在位置
-o	输出文档的位置
-t	自定义模板的位置

Grunt 模块

A separate grunt module is supported, visit github.com/apidoc/grunt-apidocor install via npm:

npm install grunt-apidoc --save-dev

模板

apiDoc 的默认模板是使用handlebars, Bootstrap, RequireJS 和 jQuery生成
包含api_data.js 和 api_project.js 的html页面.

默认模板支持, 版本信息 和 版本之间的对比

view default demo

自定义模板

通过使用apiDoc生成的api_data.js和api_project.js,或者使用api_data.json,api_project.json等配置文件自定义模板.
View the source on https://github.com/apidoc/apidoc/tree/master/template

Extend

apiDoc can be extended with your own parameters (if something is not available that you need). Look at lib/parsers/, lib/workers/, and lib/parsers/ directories in the apidoc/apidoc-core project for examples. parser
split the parameter data, worker
processes additional functions with all found data and filter
reduce the data to needed things.
Example usage: apidoc --parse-filters myFilter=pathToMyFilter/myFilter.js

Or fork the whole project and create a pull request to make apiDoc better.

配置

放置在项目根目录的配置项文件apidoc.json包含了关于项目的基本信息.例如: 标题,简述, 版本号, 配置项如头尾设置.

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

如果你使用package.json,可以在其中添加一个选项

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

Settins for apidoc.json

name	Description
name	项目名称.如果apidoc.json不存在,apidoc会自动寻找package.json里面的配置项
version	项目版本号
description	项目介绍
title	浏览器标题
url	文档路径前缀. 例如:https://api.github/com
sampleUrl	为测试api,提供的测试地址.详情见@apiSampleRequest
header	title 导航栏开头标题, filename 以md形式存储内容.
footer	title 导航栏结尾标题, filename 以md形式存储内容.
order	排序api名称或者组名. 默认:"order": [ "Error", "Define", "PostTitleAndError", "PostError"]

模板设置

"template":{
  "forceLanguage":"en", //浏览器会根据本地语言自动设置,不建议配置
  "withCompare":true/false, //默认true,比较不同版本的接口
  "withGenerator":true/false, //默认true,在footer输出生成信息,例如创建时间
  "JQueryAjaxSetup":Object //Set [default values](http://api.jquery.com/jquery.ajaxsetup/) for Ajax requests.
}

Header / Footer

{ 
  "header": { 
    "title": "My own header title", 
    "filename": "header.md" 
  }, 
  "footer": { 
    "title": "My own footer title", 
    "filename": "footer.md" 
  }
}

apiDoc-Params

@api

 @api {method} path [title]

Name	Description
method	请求方式 DELETE,GET,POST,PUT,...
path	接口路径
title	可选, 简单说明

例子:

/**
 * @api {get} /user/:id Users unique ID.
 */

@apiDefine

  @apiDefine name [title] 
  [description]

类似自定义方法
在每个接口块里只用使用一次@apiDefine
通过@apiUse导入到接口块里

Name	Description
name	唯一值,同一个name值可以在不同的@apiVersion中定义
title	可选, 小标题,仅能在@apiPermission和@apiParam(name)等方法中使用
description	可选,方法的详细说明不能与name同行,需要新起一行,可以换行.只能使用在@apiPermission中

例子:

 /**
  * @apiDefine MyError
  * @apiError UserNotFound The <code>id</code> of the User was not found.
  */

/**
  * @apiDefine admin User access only
  * This optional description belong to to the group admin.
  */

  /**
  * @api {get} /user/:id
  * @apiPermission admin
  */