关于
apidoc 是一个简单的 RESTful API 文档生成工具,它从代码注释中提取特定格式的内容生成文档。支持诸如 Go、Java、C++、Rust 等大部分开发语言,具体可使用 apidoc lang 命令行查看所有的支持列表。
apidoc 拥有以下特点:
- 跨平台,linux、windows、macOS 等都支持;
- 支持语言广泛,即使是不支持,也很方便扩展;
- 支持多个不同语言的多个项目生成一份文档;
- 输出模板可自定义;
- 根据文档生成 mock 数据;
以下是一段简短的 C 语言风格代码下的示例:
![ff743fcf382159b0b10ee5a9ab549afd.png](https://i-blog.csdnimg.cn/blog_migrate/9c27628c9e53b96d1fe99172d07bd8f5.jpeg)
使用
环境变量
apidoc 会读取 LANG 的环境变量作为其本地化的依据,若想指定其它语种,可以手动定 LANG 环境变量:LANG=zh-Hant apidoc。在 windows 系统中,若不存在 LANG 环境变量,则会调用 GetUserDefaultLocaleName 函数来获取相应的语言信息。
命令行
可以通过 apidoc help 查看命令行支持的子命令。包含了以下几个:
![bc5d17ac0c53856593b7ac08c0283db1.png](https://i-blog.csdnimg.cn/blog_migrate/a10bf8b2cf105020c0a3b8e16252f669.jpeg)
.apidoc.yaml
配置文件名固定为 .apidoc.yaml,格式为 YAML,可参考 .apidoc.yaml。文件可以通过命令 apidoc detect 生成。主要包含了以几个配置项:
![ea7e6059bc11a5f8930345eb1850aefb.png](https://i-blog.csdnimg.cn/blog_migrate/8158eca2762e95e0005266ea0fdbd225.jpeg)
文档格式
文档采用 XML 格式。存在两个顶级标签:apidoc 和 api,用于描述整体内容和具体接口信息。
文档被从注释中提取之后,最终会被合并成一个 XML 文件,在该文件中 api 作为 apidoc 的一个子元素存在,如果你的项目不想把文档写在注释中,也可以直接编写一个完整的 XML 文件,将 api 作为 apidoc 的一个子元素。
以下是对各个 XML 元素以及参数介绍,其中以 @ 开头的表示 XML 属性;. 表示为当前元素的内容;其它表示子元素。
![0fa623ce15a24dccee2d8bc1eb3033b4.png](https://i-blog.csdnimg.cn/blog_migrate/326e522bc4a6dcfc23eeb18a3b5b8b1c.jpeg)
这里就不一一列举了,关于源码已经全部上传好了,有需要的读者朋友关注我后记得帮忙转发、转发、转发一下,私信【源码】就可以免费获取到了