【ApiDoc】官方文档(翻译)

【ApiDoc】官方文档(翻译)

 

本文主要参考

• ApiDoc官方文档

一、apidoc简介

apidoc是一款可以有源代码中的注释直接自动生成api接口文档的工具，它几乎支持目前主流的所有风格的注释。例如：
Javadoc风格注释(可以在C#, Go, Dart, Java, JavaScript, PHP, TypeScript等语言中使用)

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

二、apidoc使用

可以通过以下命令安装apidoc:

npm install apidoc -g

运行：

apidoc -i myapp/ -o apidoc/ -t mytemplate/

2.1 apidoc 命令参数列表：

参数	描述
-h, --help	查看帮助文档
-f --file-filters	指定读取文件的文件名过滤正则表达式(可指定多个) 例如: apidoc -f ".*\\.js$" -f ".*\\.ts$" 意为只读取后缀名为js和ts的文件 默认值:.clj .cls .coffee .cpp .cs .dart .erl .exs? .go .groovy .ino? .java .js .jsx .kt .litcoffee lua .p .php? .pl .pm .py .rb .scala .ts .vue
-e --exclude-filters	指定不读取的文件名过滤正则表达式(可指定多个) 例如:apidoc -e ".*\\.js$" 意为不读取后缀名为js的文件 默认:''
-i, --input	指定读取源文件的目录 例如：apidoc -i myapp/ 意为读取myapp/目录下面的源文件 默认值:./
-o, --output	指定输出文档的目录 例如：apidoc -o doc/ 意为输出文档到doc目录下 默认值:./doc/
-t, --template	指定输出的模板文件 例如:apidoc -t mytemplate/ 默认:path.join(__dirname, '../template/')(使用默认模板)
-c, --config	指定包含配置文件(apidoc.json)的目录 例如:apidoc -c config/ 默认:./
-p, --private	输出的文档中是否包含私有api 例如:apidoc -p true 默认:false
-v, --verbose	是否输出详细的debug信息 例如:apidoc -v true 默认:false

2.2 配置(apidoc.json)

每次导出接口文档都必须要让apidoc读取到apidoc.json文件(如果未添加配置文件，导出报错)，你可以在你项目的根目录下添加apidoc.json文件，这个文件主要包含一些项目的描述信息，比如标题、简短的描述、版本等，你也可以加入一些可选的配置项，比如页眉、页脚、模板等。
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文件(例如:node.js工程)，那么你可以将apidoc.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会尝试从pakcage.json文件中读取
version	版本 如果apidoc.json文件中没有配置该参数，apidoc会尝试从pakcage.json文件中读取
description	工程描述 如果apidoc.json文件中没有配置该参数，apid