project api-doc {🖫 8, ⚐ 7, ★ 28}

ares333/api-doc

A powerful api document management system written in php

Friday, July 27, 2018
by ares333
Repository
5 Watchers
28 Stars
8 Installations

CSS
0 Dependents
0 Suggesters
13 Forks
0 Open issues
7 Versions
100 % Grown

The README.md

关于

项目已经大量用在生产环境。, _(*1)

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

特性

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

原理

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

需求

PHP: >=5.3, _(*3)

ext-yaf: >=2.3.3, _(*4)

安装

composer create-project ares333/api-doc

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

数据文件在 app/data/api, _(*5)

Demo

用户名 admin
密码  admin

文档格式

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

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