Python ApiDoc 工具手册中文译本

一、快速开始

安装

使用Ubuntu环境，安装命令如下：

sudo apt-get install python3-pip
sudo pip3 install apidoc

apidoc依赖三个库，分别是：Jinja2==2.7.3、PyYAML==3.11、jsonschema==2.4.0

如果python3-pip不存在，还可以使用如下命令安装：

sudo apt-get install python3-setuptools
sudo easy_install3 pip
sudo pip3-2 install apidoc

示例

使用如下命令，运行一个简单的示例：

mkdir apidoc
cd apidoc
wget https://raw.github.com/SolutionsCloud/apidoc/master/example/demo/source.yml
apidoc -i source.yml -o output/index.html
firefox output/index.html

通过浏览器看到的效果如图：

二、使用方法

命令行参数

通过如下命令查看apidoc的完整命令行参数：apidoc -h

usage: apidoc [-h] [-c CONFIG] [-i DIRECTORY OR FILE [DIRECTORY OR FILE ...]]
              [-o FILE] [-v] [-n] [-a ARGUMENT [ARGUMENT ...]] [-y] [-w] [-q]
              [-qq] [-t]

Base command-line interface for ApiDoc

optional arguments:
  -h, --help            show this help message and exit
  -c CONFIG, --config CONFIG
                        configuration file
  -i DIRECTORY OR FILE [DIRECTORY OR FILE ...], --input DIRECTORY OR FILE [DIRECTORY OR FILE ...]
                        directories and/or files containing documentation's
                        source files
  -o FILE, --output FILE
                        rendered output file
  -v, --version         show program's version number and exit
  -n, --no-validate     disable validation
  -a ARGUMENT [ARGUMENT ...], --arguments ARGUMENT [ARGUMENT ...]
                        documentation's arguments arg1=value1 arg2=value2
  -y, --dry-run         analyse config's and source's files without building
                        the documentation
  -w, --watch           re-render the documentation each time a source's file
                        or a template's file changes
  -q, --quiet           does not display logging information below warning
                        level
  -qq, --silence        does not display any logging information
  -t, --traceback       display traceback when an exception raised

将上述命令行参数简单翻译就是：

• -h 查看帮助信息

• -c 指定配置文件

• -i 指定输入，可以是目录或者文件

• -o 指定输出，输出的只能是文件

• -v 查看版本信息

• -n 关闭验证

• -a 指定文档的参数arg1=value1 arg2=value2

• -y 仅对配置或源文件做分析不输出文档

• -w 每次源文件或模板文件变化就重新生成文档

• -q 告警级别以下的日志不显示

• -qq 不显示任何日志

• -t 如果异常则展示

基本参数

通过指定的源文件生成文档：

apidoc -i ./example/source_simple/simple.yml

通过多个源文件生成文档：

apidoc -i ./example/source_simple/one.yml ./example/source_simple/two.yml

通过包含源文件的目录生成文档：

apidoc -i ./example/source_simple/

通过指定配置文件生成文档：

apidoc -c ./example/config/config.yaml

组合上述参数生成文档：

apidoc -c ./config.yaml -i ./folder1/ ./folder2/ /folder3/file.yaml /folder3/file.json

仅分析源文件不生成文档：

apidoc -i ./example/source_simple/simple.yml -y

每次文件变化都自动重新生成文档：

apidoc -i ./example/souce_simple/simple.yml -w

显示更少的日志生成文档：

apidoc -i ./example/source_simple/simple.yml -q
apidoc -i ./example/source_simple/simple.yml -qq

显示异常生成文档：

apidoc -i ./example/source_simple/simple.yml -t

三、配置文件格式

ApiDoc可以通过命令行参数或者一个包含选项的配置文件来生成文档。配置文件的格式可以是YAML或者JSON，文件后缀必须是：.yaml、.yml、.json

示例

通过指定配置文件为参数来生成文档：

apidoc -c ./path-to-config.yaml

一个简单的配置文件示例

最简单的配置文件：

input:
  locations:
    - ./sources/one.yml
output:
  location:
    ./output/sample.html

最基本的配置文件：

input:
  locations:
    - ./sources
    - ./sources2/one.yml
  arguments:
    url: api.sfr.com
filter:
  versions:
    excludes:
      - v2
output:
  location: ./output/sample.html
  componants: local
  template: default

对上述参数进行详解：

input

input定义了源文件的位置，包含三个子选项：

• locations：包含了文件列表、目录

• validate：验证开关，验证源文件是否符合JSON格式验证

• arguments：包含了源文件里所需的参数、变量

作为配置文件，源文件必须是上面提到的yaml、yml、json，当指定位置为目录时，目录下所有的源文件都会被生成文档，且配置文件至少包含一个指定的源文件。

一个完整的input例子：

input:
  locations:
    - ./project/api-sources
    - ../common-api/sources
    -