使用 apidoc - 文章教程

使用 apidoc

发布于 2021-10-07 字数 5944 浏览 918 评论 0

安装

可以直接从 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,会自动生成一张指定大小的图片并把地址返回给用户,其大小由查询参数 widthheight 指定,未指定则是 500×500。图片类型则通过用户提交的 Accept 报头获取,目前支持 image/gifimage/pngimage/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+xmlopenapi+jsonopenapi+yaml
output.path string 指定输出的文件名,包含路径信息。
output.tags string[] 只输出与这些标签相关联的文档,默认为全部。
output.style string 为 XML 文件指定的 XSL 文件
output.namespace bool 是否输出命名空间
output.namespace-prefix string 如果输出了命名空间,还可以指定命名空间前缀。

如果你对这篇文章有疑问,欢迎到本站 社区 发帖提问或使用手Q扫描下方二维码加群参与讨论,获取更多帮助。

扫码加入群聊

发布评论

需要 登录 才能够评论, 你可以免费 注册 一个本站的账号。

目前还没有任何评论,快来抢沙发吧!

关于作者

JSmiles

生命进入颠沛而奔忙的本质状态,并将以不断告别和相遇的陈旧方式继续下去。

2512 文章
30 评论
82839 人气
更多

推荐作者

qianbiandeboy

文章 0 评论 0

少女净妖师

文章 2 评论 0

zangqw

文章 0 评论 0

qq_7HKsl

文章 0 评论 0

伪装你

文章 1 评论 0