README

概述

适用于PHP项目的tplapidoc是一个自动化文档接口生成工具。基于自定义模板生成API接口文档。

安装

$ mkdir /data1
$ cd /data1
$ composer require itititi/tplapidoc

使用

常规方法

[用法] cmd 源路径 目标路径

示例：/data1/vendor/bin/tplapidoc /data1/src/Demo.php /data1/dst

建议将其编写为shell脚本以方便使用，如下：

$ vim apidoc.sh

#!/bin/bash

msg='更新接口'
if test ! -z $1 ;then
    msg=$1
fi

src=/data1/src/Demo.php
dst=/data1/dst/
cmd=/data1/vendor/bin/tplapidoc 

cd $dst; find $dst ! -name '公共信息.md' -type f -exec rm -f {} \;
$cmd $src $dst

git add -A .
git commit -m "$msg"; git push

开发说明

解析接口来源文件

/data1/src/Demo.php

<?php
class Demo extends A {
    /**
     * @name 测试
     * @description 无
     * @method POST
     * @param id int n 唯一id
     * @param name string n 姓名
     * @return json
     * // succ
     * {
     *    retcode: 2000000,
     *    msg: '操作成功'
     * }
     * // fail
     * {
     *    retcode: '错误编码',
     *    msg: '错误信息'
     * }
     */
    public function test() {
    }

配置模板文件

/data1/vendor/itititi/tplapidoc/src/tpl/markdown.wiki

#### 接口名称
@name

#### 接口描述
@description

#### 基本信息
| 属性 | 内容 |
| -------- | -------- |
| Url | Path+@path |
| Method | @method |
| Charset | UTF-8 |

#### 请求参数
| 参数 | 类型 | 必传 | 备注 | 
| - | - | - | - | - |
@param

#### 结果返回
| 状态 | 内容 |
| -------- | -------- |
| succ/fail | 详见：response |

### response
@return

生成的文档文件 </data1/dst/测试.md>

#### 接口名称
测试

#### 接口描述
无

#### 基本信息
| 属性 | 内容 |
| -------- | -------- |
| Url | Path+/demo/test |
| Method | POST |
| Charset | UTF-8 |

#### 请求参数
| 参数 | 类型 | 必传 | 备注 | 
| - | - | - | - | - |
| id | int | n | 唯一id |
| name | string | n | 姓名 |


#### 结果返回
| 状态 | 内容 |
| -------- | -------- |
| succ/fail | 详见：response |

### response
// succ
{
   retcode: 2000000,
   msg: '操作成功'
}
// fail
{
   retcode: '错误编码',
   msg: '错误信息'
}

寄语

目前仅实现了基于GitLab上Wiki Markdown语法的格式。欢迎关注该项目的同学贡献自己的力量。