概述
适用于php项目的 tplapidoc 是自动化文档接口生成工具。基于自定义模板生产api接口文档。, (*1)
安装
$ mkdir /data1
$ cd /data1
$ composer require itititi/tplapidoc
使用
普通方式
[usage] cmd src dst, (*2)
示例：/data1/vendor/bin/tplapidoc /data1/src/Demo.php /data1/dst, (*3)
建议写成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, (*4)
<?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, (*5)
#### 接口名称
@name
#### 接口描述
@description
#### 基本信息
| 属性 | 内容 |
| -------- | -------- |
| Url | Path+@path |
| Method | @method |
| Charset | UTF-8 |
#### 请求参数
| 参数 | 类型 | 必传 | 备注 |
| - | - | - | - | - |
@param
#### 结果返回
| 状态 | 内容 |
| -------- | -------- |
| succ/fail | 详见：response |
### response
@return
``` bash, (*6)
接口名称
测试, (*7)
接口描述
无, (*8)
基本信息
| 属性 |
内容 |
| 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: '错误信息'
}
```, (*9)
寄言
目前只实现了基于gitlab上wiki markdown语法格式。欢迎关注到该项目的同学贡献自己的一份力量。, (*10)
Wallogit.com
