ares333/api-doc

This package is abandoned and no longer maintained. No replacement package was suggested.

A powerful api document management system written in php

Installs: 19

Dependents: 0

Suggesters: 0

Security: 0

Stars: 31

Watchers: 5

Forks: 13

Open Issues: 0

Language:CSS

Type:project

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

This package is auto-updated.

Last update: 2024-04-27 04:38:32 UTC


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