README

基于 thinkphp5 的doc文档扩展

[目录]

说明

thinkphp5编写的自动生成文档功能；

• 文档生成

简洁，优雅，无需额外的文档工具;

安装

• 如果想在您的TP5项目中使用，那么可以直接使用

composer require curselby/tp5-doc

• 如果是新项目，先要创建TP5项目，然后再require

composer create-project topthink/think api  --prefer-dist
composer require curselby/tp5-doc

• 使用生成文档需要在public/static/下安装hadmin

cd /public/static/
git clone  https://git.oschina.net/curselby/hadmin.git

使用

1. 创建Doc文档显示控制器    wiki 继承 Tp5Doc\doc\Doc;

2. 配置路由

   'wiki'=>'demo/Wiki/index',//文档

3.配置文档显示目录

    /**
     * 获取文档
     * @return mixed
     */
    public static function getApiDocList()
    {
        //todo 可以写配置文件或数据
        $apiList = Config::get('api_doc');
        return $apiList;
    }

可以改写此方法以存储以无限级的方式，为了方便采用的是配置方式

TP5 增加额外配置 创建application/extra/api_doc.php 文件

return [
    '1' => ['name' => '测试文档', 'id' => '1', 'parent' => '0', 'class'=>'','readme' =>''],//下面有子列表为一级目录
    '2' => ['name' => '获取权限', 'id' => '2', 'parent' => '1', 'class'=>'','readme' => '/doc/md/auth.md'],//没有接口的文档，加载markdown文档
    '3' => ['name' => '用户接口', 'id' => '3', 'parent' => '1', 'readme' => '','class'=>\app\test\controller\User::class],//User接口文档
];

3.具体接口文档配置

• 接口描述部分(类文件的注释)

/**
 * Class User
 * @title 用户接口
 * @url /v1/user
 * @desc  有关于用户的接口
 * @version 1.0
 * @readme /doc/md/user.md
 */
class User extends Base{}

• 具体接口文档

1. 接口描述信息(注释填写)

       /**
        * @title 获取用户信息
        * @desc 获取用户信息
        * @readme /doc/md/method.md
        */
      public function getResponse(\think\Request $request){}

2.请求参数

    /**
     * 参数规则
     * @name 字段名称
     * @type 类型
     * @require 是否必须
     * @default 默认值
     * @desc 说明
     * @range 范围
     * @return array
     */
    public static function getRules()
    {
        $rules = [
                //共用参数
                'all'=>[
                    'time'=> ['name' => 'time', 'type' => 'int', 'require' => 'true', 'default' => '', 'desc' => '时间戳', 'range' => '',]
                ],

                'get'=>[
                    'id' => ['name' => 'id', 'type' => 'int', 'require' => 'true', 'default' => '', 'desc' => '用户id', 'range' => '',]
                ],
                'post'=>[
                    'username' => ['name' => 'username', 'type' => 'string', 'require' => 'true', 'default' => '', 'desc' => '用户名', 'range' => '',],
                    'age' => ['name' => 'age', 'type' => 'int', 'require' => 'true', 'default' => '18', 'desc' => '年龄', 'range' => '0-200',],
                ]
        ];
        //合并父级类参数
        return array_merge(parent::getRules(),$rules);
    }

1. 返回参数(注释填写)

     * @return int id ID
     * @return string username 错误信息
     * @return int age 年龄

类型填写规则

'string'    => '字符串',
'int'       => '整型',
'float'     => '浮点型',
'boolean'   => '布尔型',
'date'      => '日期',
'array'     => '数组',
'fixed'     => '固定值',
'enum'      => '枚举类型',
'object'    => '对象',

整体效果