library laravel-api-helper

brooksyang/laravel-api-helper

Api doc generator for laravel 5

, _(*1)

介绍

该项目是基于 Laravel 5.5 的API文档生成工具，根据 laravel 路由及注释文件生成可视化 api 文档，内置接口调试工具。, _(*2)

Demo

点击访问, _(*3)

项目依赖

更新日志

v2.0.0 2019-03-29 - 重构 移除 GuzzleHttp 依赖，接口测试改用 Laravel 内置的 Request 类请求 - 重构 移除 ResponseHelper Trait, _(*4)

v1.6.0 2019-03-19 - 新增 支持资源路由（参数接收方式见「使用示例」） - 新增 内置接口访问统计（需启用 request.counter 中间件）, _(*5)

v1.5.4 2019-03-19 - 新增 请求 api 设置 Accept 为 json, _(*6)

v1.5.3 2019-03-01 - 优化 样式调整, _(*7)

v1.5.2 2019-03-01 - 新增 可选是否开启文档功能，默认开启 - 优化 移除js公共资源, _(*8)

v1.5.1 2019-03-01 - 优化 文件结构调整, _(*9)

v1.5.0 2019-03-01 - 新增 测试工具提供 Pretty、Raw、Preview 三种响应结果视图, _(*10)

v1.4.7 2019-02-28 - 新增 压力测试调整为可选功能，默认关闭, _(*11)

v1.4.6 2019-02-28 - 优化 压缩css文件, _(*12)

v1.4.5 2019-02-28 - 新增 测试工具允许使用 dd、dump、echo 等方法直接打印数据 - 优化 测试工具返回完整异常信息, _(*13)

v1.4.4 2018-07-20 - 优化 左侧菜单样式优化, _(*14)

v1.4.3 2018-06-28 - 优化 模块分组优化, _(*15)

v1.4.2 2018-06-28 - 新增 新增模块分组功能，以区分不同命名空间下的重名文件夹, _(*16)

v1.4.1 2018-06-24 - 修复 修复api-helper配置文件的bug, _(*17)

v1.4.0 2018-06-24 - 新增 可指定文档生成的命名空间，向下兼容v1.3，默认命名空间为App\Http\Controllers, _(*18)

v1.3.2 2018-03-31 - 优化 压力测试安全机制优化, _(*19)

v1.3.0 2018-02-13 - 新增表单支持文件上传, _(*20)

v1.2.0 2018-01-22 - 新增 新增ResponseHelper Trait，封装常用api返回方法, _(*21)

v1.1.1 2018-01-22 - 新增 Guzzle 请求异常处理, _(*22)

v1.1.0 2017-12-18 - 新增 支持在线ApacheBench服务器压力测试，并缓存最近一次压测结果，在接口列表及详情页展示, _(*23)

安装

composer require brooksyang/laravel-api-helper

配置

打印配置文件，及静态资源，该命令将生成 config/api-helper.php，及 /public/vendor/api_helper 文件夹, _(*24)

php artisan vendor:publish --tag=api-helper

api-helper.php 配置项说明, _(*25)

cache_tag_prefix // 缓存前缀，默认为api_helper，建议不同项目设置不同前缀以防止冲突

cache_ttl // 缓存时长，默认120分钟，可根据项目需求自行设置

api_base_url // 接口请求基础地址，默认为当前<host_name>，一般情况下不需要配置，若存在内外网不通的情况，可设置为相应内网地址

api_doc // v1.5.2 新增，是否开启Api文档及测试工具，默认 true

api_pressure_test // v1.4.7 新增，是否开启压力测试功能，默认 false

namespaces // 指定生成Api文档命名空间，数组，key为group，value为namespace，请确保namspace之间没有交集，否则小集合将被忽略

注意：请确保所配置的命名空间下存在次级命名空间，否则将被忽略，次级命名空间将作为模块名，更深层次命名空间与次级命名空间同级，例：, _(*26)

namespaces 配置示例, _(*27)

namespaces => [
    'Helper' => 'BrooksYang\LaravelApiHelper\Controllers\BuiltIn', // v1.6.0 新增，内置接口访问统计
    'App'  => 'App\Http\Controllers', // 生效
    'Test' => 'App\Http\Controllers\Test', // 无效
    'Api'  => 'Api\Controllers' // 生效
];

该配置中，「App」包含「Test」，「App」与「Api」同级，所以「Test」被忽略, _(*28)

代码目录结构, _(*29)

|--app
    |--Http
        |--Controllers
            |--TestController // 无效
            |--Demo
                |--DemoController // 生效
                |--Deep
                    |--DeepController // 生效，与DemoController 同级
|--Api
    |--Controllers
        |--Xxx
            |--XxxController // 生效

以上配置，TestController被忽略，DemoController 生效，DeepController与DemoController同级生效，XxxController生效, _(*30)

启用接口访问统计（可选）

vim app/Http/Kernel，在 $middlewareGroups 中添加 'request.counter' 中间件, _(*31)

/**
 * The application's route middleware groups.
 *
 * @var array
 */
protected $middlewareGroups = [
    // ***

    'api' => [
        'throttle:60,1',
        'bindings',
        'request.counter', // 启用「接口访问统计」中间件
    ],
];

设置缓存驱动

修改 .env 文件，将缓存驱动设置为redis（推荐）, _(*32)

CACHE_DRIVER=redis

若本机没有安装redis，可暂时设置为array, _(*33)

CACHE_DRIVER=array

使用示例

use BrooksYang\LaravelApiHelper\Traits\ResponseHelper;

/**
 * 这里是api标题
 *
 * @return \Illuminate\Http\Response
 */
public function index(Request $request)
{
    // 支持以下三种方式接收表单参数
    $paramA = $request->input('param_a'); // 参数一说明
    $paramB = $request->get('param_b'); // 参数二说明
    $paramC = Input::get('param_c'); // 参数三说明

    // 针对资源路由（v1.6.0 新增）
    $param = $request->input('{param}'); // 资源路由参数接收

    // 支持接收表单文件（v1.3.0新增）
    $file = $request->file('upload_file');

    // 以下是返回内容，ResponseHelper封装了三种返回方法，不强制使用，可自定义返回数据结构
    return $this->jsonResponse(['test' => 'blablabla'], '操作成功'); // 方式一，操作成功，返回数据及提示信息
    return $this->errorResponse(['code' => 'xxx', 'msg' => '操作失败']); // 方式二，操作失败，返回错误码及错误消息
    return $this->msgResponse('操作成功'); // 方式三，操作成功，仅返回成功提示消息
}

注意

若设置了redis驱动，添加了新的api之后，需执行清除缓存操作（若缓存驱动为array，则跳过该步骤）, _(*34)

php artisan cache:clear

访问地址

http://<HOST_NAME>/api/docs

TODO LIST

• [x] 支持资源路由
• [x] 接口访问统计
• [ ] 记录接口访问日志
• [ ] 返回参数自动生成文档