以下内容,均为官方文档的中文译稿,如在学习过程中发现有误,请不吝赐教,指正修改。
1. DEMO
访问站点:http://apidocjs.com/#demo
查看演示效果。
2. 入门
2.1 前言
文档中所有的示例都使用了Javadoc风格(也可使用C#、Go、Dart、Java、JavaScript、PHP、TypeScript以及其他支持Javadoc的语言):
/**
* This is a comment.
*/
对于其他语言使用其他特定的多行注释代码:
- CoffeeScript
###
This is a comment.
###
- Elixir
@apidoc """
This is a comment.
"""
- Erlang(%在注释中是可选的)
%{
% This is a comment.
%}
- Perl(Doxygen)
#**
# This is a comment.
#*
- Python
"""
This is a comment.
"""
- Ruby
=begin
This is a comment.
=end
- Lua
--[[
This is a comment.
--]]
2.2 安装
这里很简单就是利用npm进行安装,详细安装过程在上面讲过:
npm install apidoc -g
2.3 运行
apidoc -i myapp/ -o apidoc/ -t mytemplate/
将目录myapp里的文件,使用目录mytemplate目录下的模板文件来生成的apidoc文档最后存储在目录apidoc下。
如果不指定参数,apiDoc会根据当前目录下全部的.cs、.dart、.erl、.go、.java、.js、.php、.py、.rb、.ts文件来生成文档到当前目录的doc目录下。
2.4 命令行
通过命令行参数查看帮助信息:
apidoc -h
重要参数讲解:
2.5 GRUNT模式
支持单独的grunt模式,参见:github.com/apidoc/grunt-apidoc
或者通过npm来安装:
npm install grunt-apidoc --save-dev
grunt是一套前端自动化工具,一个基于nodejs的命令行工具,一般用于:压缩文件、合并文件、简单语法检查。
关于grunt的可访问官方网站获取详细信息:https://gruntjs.com/
这里暂不做深入讨论。
2.6 模板
apiDoc包含一个默认的模板使用handlebars、Bootstrap、RequireJS和jQuery用于输出生成的api_data.js
和api_project.js
作为一个html页面。
默认情况下生成的apiDoc文档使用复杂的模板,支持:
versioning:查看你的API接口不同版本
compare:对比你的API接口在两个版本之间的变化
查看示例,这里我在官方演示demo里随便对比了一个版本差异效果如图:
创建属于自己的模板
当然你也可以创建一个你自己的模板来生成apiDoc文档的api_data.js
、api_project.js
或者仅json文件api_data.json
、api_project.json
。
查看模板的源代码:https://github.com/apidoc/apidoc/tree/master/template
2.7 扩展
apiDoc可以通过你自己的参数进行扩展(如果有一些是你不需要的)。以在apidoc/apidoc-core
项目上的lib/parsers/
、lib/workers
和lib/filters/
目录为例,parser
分离参数数据,worker
用所有找到的数据处理附件函数,filter
减少数据需要的东西。
示例:
apidoc --parse-filters myFilter=pathToMyFilter/myFilter.js
这要比请求整个项目创建来生成apiDoc要好。
2.8 配置文件(apidoc.json)
apidoc.json
是可选的在你的项目根目录下,包含你项目的一些基本信息,比如标题、摘要、版本等,配置项像header/footer
或者模板特定选项。
apidoc.json示例:
{
"name": "apidoc-example",
"version": "0.3.0",
"description": "apiDoc example project",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1",
"header": {
"title": "My own header title",
"filename": "header.md"
},
"footer": {
"title": "My own footer title",
"filename": "footer.md"
},
"order": [
"GetUser",
"PostUser"
],
"template": {
"withCompare": true,
"withGenerator": true
}
}
如果你使用了package.json
(eg:在node.js项目里),所有的apidos.json
配置可以同样由package.json
来完成,只需要把它们添加到"apidoc":{}
参数下即可。
package.json示例:
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"apidoc": {
"title": "Custom apiDoc browser title",
"url": "https://api.github.com/v1"
}
}
apidoc.json的基本配置信息:
参数名 | 描述 |
---|---|
name | 项目名称,如果在apidoc.json 中不存在此字段,apiDoc将会通过package.json 中的值来命名 |
version | 项目版本,如果在apidoc.json 中不存在此字段,apiDoc将会通过package.json 中的值来命名 |
description | 项目描述,如果在apidoc.json 中不存在此字段,apiDoc将会通过package.json 中的值来命名 |
title | 浏览器标题 |
url | api接口路径前缀(端点),eg:https://api.github.com/v1 |
sampleUrl | 如果设置了,那么一个用于测试api方法(发送请求)将会可用。具体参见@apiSampleRequest获取更多细节 |
header | |
|
对于包含header.md文件的导航文本(参见:Header/Footer ) |
|
对于包含header.md文件的文件名(markdown文件) |
footer | |
|
对于包含footer.md文件的导航文本 |
|
对于包含footer.md文件的文件名(markdown文件) |
order | 输出的api名称/组名称顺序列表。未定义的名称将自动显示在最后 |
"order":["Error", "Define", "PostTitleAndError", "PostError"] |
模板中的特殊配置
接下来的这些配置都是apiDoc默认模板里的特殊配置。
参数名 | 类型 | 描述 |
---|---|---|
template | ||
|
String | 禁用浏览器的语言自动检测并且设置特定的区域设置,例如:de 、en ,查看可用区域:here |
|
Boolean | 允许与旧版本的API进行比较,默认值为:true |
|
Boolean | 在页脚输出生成器信息,默认值为:true |
|
Object | 设置Ajax请求的默认值 |
2.9 页眉/页脚
在你项目的apidoc.json
配置文件中你可以增加页眉和页脚。
标题将会在导航中可见,文件名应该是markdown格式。
示例:
{
"header": {
"title": "My own header title",
"filename": "header.md"
},
"footer": {
"title": "My own footer title",
"filename": "footer.md"
}
}
3. 示例
一个小的演示介绍示例:speakerdeck.com
3.1 基本
在基本示例中我们有一个小的项目文件和一个apidoc.json配置文件。
演示效果就不截图了,大家访问这个地址查看即可:http://apidocjs.com/example_basic/
apidoc.json
完整的代码:
{
"name": "example-basic",
"version": "0.1.0",
"description": "apiDoc basic example",
"template": {
"withCompare": false
}
}
通过apidoc.json
apiDoc获取到你项目的名称、版本、描述信息,这个文件是可选的,它取决于你的模板里是否要求有这些数据。
example.js
完整的代码:
/*
* Basic Example
*
* This is a basic