使用 apidoc

Question

安装

可以直接从 https://github.com/caixw/apidoc/releases 查找你需要的版本下载，放入 PATH 中即可使用。如果没有你需要的平台文件，则需要从源代码编译：

• 下载 Go；
• 下载源代码，git clone github.com/caixw/apidoc；
• 执行代码中 build/build.sh 或是 build/build.cmd 进行编译；
• 编译好的文件存放在 cmd/apidoc 下，可以将该文件放置在 PATH 目录；

环境变量

apidoc 会读取 LANG 的环境变量作为其本地化的依据，若想指定其它语种，可以手动指定 LANG 环境变量：LANG=zh-Hant apidoc。在 windows 系统中，若不存在 LANG 环境变量，则会调用 GetUserDefaultLocaleName 函数来获取相应的语言信息。

本地化的 ID 值，理论上只要 BCP47 支持的都能正确识别。也支持 Linux 下带编码的格式，比如：zh_CN.UTF-8。

IDE 插件

apidoc 支持以 LSP 模式运行：apidoc lsp -p=":8080" -m=stdio -h。所有支持 LSP 的 IDE 和编辑器很容易实现对应的插件。目前官方已经提供了针对 vscode 的插件：apidoc.vscode。

Mock

mock 子命令可以让 apidoc 根据文档动态生成 mock 数据，mock 子命令提供了大量的配置项，以使生成的数据更有随机性，具体的命令项可以通过 apidoc help mock 查看。

如果数据类型为 string.image，会自动生成一张指定大小的图片并把地址返回给用户，其大小由查询参数 width 和 height 指定，未指定则是 500x500。图片类型则通过用户提交的 Accept 报头获取，目前支持 image/gif、image/png 和 image/jpeg 三种类型。

使用 mock 也有一定的局限性：只能判断提交的数据是否符合要求，但是无法理解数据代码的含义，比如 URL 中包含 page=2，能判断 page 的值格式是否正确，但无法给用户返回第二页的数据。Mock 在验证数据正确性和初期用于展示数据内容还是很有用的。

命令行

可以通过 apidoc help 查看命令行支持的子命令。包含了以下几个：

名称	描述
build	生成文档内容
detect	根据目录下的内容生成配置文件
help	显示帮助信息
lang	显示所有支持的语言
locale	显示所有支持的本地化内容
lsp	启动 language server protocol 服务
mock	启用 mock 服务
static	启用静态文件服务
syntax	测试语法的正确性
version	显示版本信息

配置文件

配置文件名固定为 .apidoc.yaml，格式为 YAML，可参考 .apidoc.yaml。文件可以通过命令 apidoc detect 生成。主要包含了以几个配置项：

名称	类型	必填	描述
version	string		此配置文件的所使用的文档版本
inputs	object[]		指定输入的数据，同一项目只能解析一种语言。
inputs.lang	string		源文件的解析方式。具体支持的类型可通过命令 apidoc lang 查看支持语言。
inputs.dir	string		需要解析的源文件所在目录
inputs.exts	string[]		只从这些扩展名的文件中查找文档
inputs.recursive	bool		是否解析子目录下的源文件
inputs.encoding	string		编码，默认为 utf-8，值可以是 character-sets 中的内容。
inputs.ignores	string[]		忽略的文件或目录，比如 node_modules 等。
output	object		控制输出行为
output.type	string		输出的类型，目前可以 apidoc+xml、openapi+json 和 openapi+yaml。
output.path	string		指定输出的文件名，包含路径信息。
output.tags	string[]		只输出与这些标签相关联的文档，默认为全部。
output.style	string		为 XML 文件指定的 XSL 文件
output.namespace	bool		是否输出命名空间
output.namespace-prefix	string		如果输出了命名空间，还可以指定命名空间前缀。