ares333/api-doc

A powerful api document management system written in php

v1.5.1 2018-06-22 06:30 UTC

Requires

• php: >=5.3
• ares333/yaf-library: ^4.0
• smarty/smarty: ^3.0
• zendframework/zend-json: ^3.0
• zendframework/zend-session: ^2.8

Requires (Dev)

• ares333/php-stubs: ^1.4

Apache-2.0

• Ares
• Zjmainstay

• api doc
• api doc management

README

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

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

安装

composer create-project ares333/api-doc

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

数据文件在 app/data/api

Demo

用户名	admin
密码	admin

文档格式

因为功能众多，数据文件都有功能展示，自行修改测试，不再对每个功能单独做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目录查找文件。

_meta标签：
	default	作为默认值被具体文档以低优先级递归合并。
	prefix	作为前缀与具体文档递归合并。
	suffix	作为后缀与具体文档递归合并。
	wraper	作为wraper与具体文档递归合并，替换内容为{key}，key为具体的键。
	var		doc中的自定义变量。
	inherit	继承其他文件，使用相对路径，后面可以跟接口根键指定继承的接口，可以多层继承！_meta.txt可以多重继承！
_unset标签：
	根据键删除合并结果中的特定值，和_meta一样在顶层定义，当前文件的内容不能unset。

关键字

键(通配符描述)
	_meta
	_unset
	\s*
	[]*
	\h
	doc		有doc就会忽略除title外的其他字段
值(正则描述)
	\t
	\\k
	\\d\d
	\\i
文件
	_meta.txt
	_root.txt （可以作为其他文档的根文档）
	_inc
变量
	{$key}		key需要替换为具体的键,doc中自己的var优先级高于php传递过来的变量

联系我们

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

QQ群:424844502