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 id 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
*/