Download the PHP package ares333/api-doc without Composer

关于

项目已经大量用在生产环境。

API文档编写是非常重要的一项工作，但是编写维护非常麻烦，本项目解决的问题是以最轻松的方式维护n个接口，每个接口n个版本， 尤其适合大量接口的使用情境。

特性

1. 无需数据库，可以用svn/git记录版本。
2. 编写非常简便，所有枯燥的工作全部由机器完成。
3. 有自己的语法格式（类似于YAML），语法非常简洁。
4. 以非常便捷的语法实现继承、递归、加前缀、后缀等常用功能。

原理

1. 解析固定语法格式的txt生成一个Trie树的数据结构。
2. 执行txt文件中定义的变量和函数处理Trie树。
3. 转换Trie树为html。

需求

PHP: >=5.3

ext-yaf: >=2.3.3

安装

1. php ini: yaf.use_namespace = 1
2. 绑定public目录为web服务器的入口
3. Enjoy!

数据文件在 app/data/api

Demo

文档格式

因为功能众多，数据文件都有功能展示，自行修改测试，不再对每个功能单独做demo。

1. 必须是UTF8格式，有无BOM均可，接口文档必须以.txt结尾。
2. 文件名可以用数字加英文句号排序，展示的时候这个数字会被忽略。
3. _meta.txt多目录可继承，文件从外到内优先级由低到高。
4. 目录结构任意，深度任意，目录中必须存在一级版本号，版本号格式很宽松。
5. 语法结构严格，文档开头结尾不能有多余空白元字符。
6. 数据以\t间隔，每行\t可以连续多个，每缩进一级代表增加一级维度。
7. 第一列作为建，后面列作为值，如果列数大于2则值为数组，如果第一列以[]开头表示此列不作为键。
8. 数字键继承或合并时不会覆盖，后面的数字键会在之前最大数的基础上累加，数字键加前缀\s可以避免这种情况。
9. 每个节点顶层主键可以使用\k代替，顶层主键#后面的字符不会作用在\k上，#字可以用来区分同名主键。
10. 返回值的demo如果以#开头不会执行wraper操作。
11. 接口可以自继承，比如引用文档中的其他节点，键使用\h实现，值是引用的键的名称（可以多个）。
12. heredoc以固定字符<<<、>>>区分。
13. 支持引用外部文件，使用\i作为替换符，后面紧跟文件名，会在当前目录的_inc目录查找文件。

关键字

联系我们

如有使用问题或建议可以加群

QQ群:424844502