Laravel使用命令根据注释一键生成接口名称文档

1、接口注释模板

/**
     * @api {POST} /admin/addAdmin 添加管理员
     * @apiVersion 1.0.0
     * @apiGrouP 管理员
     * @apiParam {String} phone 必填-手机号
     * @apiParam {String} nickname 必填-昵称
     * @apiParam {String} password 必填-密码
     * @apiParam {File} image 选填-头像
     * @apiSuccessExample {json} Success-Response:
     * HTTP/1.1 200 OK
     *
     * @apiSampleRequest off
     * @apiDescription
     * 【author】：浪里小白龙
     * 【createTime】：9:59 2023-07-10
     */
    public function addAdmin(AdminRule $request, AdminService $service)
    {
        $data['phone'] = $request->input('phone');
        $data['nickname'] = $request->input('nickname');
        $data['password'] = $request->input('password');
        $data['image'] = $request->file('image')??'';

        return $this->back($service->addAdmin($data));
    }

2、在namespace App\Console\Commands下创建OperationType类：

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Str;
use ReflectionClass;
use Route;
use DB;
use App\Model\OperationType;
use App\Http\Middleware\VerifyPermissions;
use Artisan;

class OperationTypeSeeder extends Command
{
    /**
     * The name and signature of the console command.
     *
     * @var string
     */
    protected $signature = 'operationType:sync';

    /**
     * The console command description.
     *
     * @var string
     */
    protected $description = '根据注释内容同步操作类型';

    /**
     * 不经过权限验证的路由
     *
     * @var array
     */
    public $exception = [
        'sanctum/csrf-cookie',
    ];

    /**
     * Create a new command instance.
     *
     * @return void
     */
    public function __construct()
    {
        parent::__construct();
    }

    /**
     * Execute the console command.
     *
     * @return mixed
     */
    public function handle()
    {
        $sortData = [];

        // 清理表
        DB::statement('SET FOREIGN_KEY_CHECKS=0;');
        OperationType::query()->truncate();
        DB::statement('SET FOREIGN_KEY_CHECKS=1;');

        foreach (Route::getRoutes()->getRoutes() as $route)
        {
            $action = $route->getAction();

            // 过滤排除路径in_array('get', $route->methods) ||
            if (in_array($route->uri(), $this->exception)) {
                continue;
            }

            // 验证控制器并执行同步
            if (array_key_exists('controller', $action))
            {
                // 获取注释
                $reflector = new ReflectionClass($route->getController());
                $comment = $reflector->getMethod($route->getActionMethod())->getDocComment();

                // 组合kv
                if (preg_match_all('/@(\w+)\s+(.*)\r?\n/m', $comment, $matches)){
                    $result = array_combine($matches[1], $matches[2]);
                }

                // 整理导入数据
                if ($result && isset($result['api'])) {
                    $row = explode(" ",$result['api']);
                    if (empty($row[2])) $row[2]='';
                    $name =  trim($row[2]);
                    $path = trim($row[1]);
                    $path = substr_replace($path, '',0,1);
                    $method = strtolower($route->methods[0]);
                    $module_str = substr($path, 0, 2);
                    if ($module_str == 'wx') {
                        $module = 2;//小程序
                    } else {
                        $module = 1;
                    }
                    $this->createOperationType($name, $path, $method, $module);
                }
            }
        }
    }

    /**
     * 创建权限
     *
     * @param [type] $name 方法名称
     * @param [type] $path 控制器名称和方法名称
     * @param [type] $method 请求方式
     * @param $module int 所属模块:1后台 2小程序
     * @return \App\Model\OperationType
     */
    private function createOperationType($name, $path, $method, $module)
    {
        return OperationType::create([
            'name' => $name,
            'path' => $path,
            'method' => $method,
            'module' => $module,
        ]);
    }
}

3、创建对应的model：App\Model\OperationType

<?php

namespace App\Model;

use Illuminate\Database\Eloquent\Model;

class OperationType extends Model
{
    //日志类型
    protected $table = 'zs_operation_type';//绑定表
    protected $primaryKey = 't_id';//绑定主键id
    public $timestamps = false;
    protected $fillable = [ //需指定字段，否则无法批量写入
        'name',
        'path',
        'method',
        'module'
    ];
}

Model文件：

class OperationType extends Model
{
    // 操作类型
    protected $table = 'hzy_operation_log';//绑定表
    protected $primaryKey = 'id';//绑定主键id
    public $timestamps = true;
    protected $fillable = [
        'name',
        'path',
        'method',
        'module',
    ];
}

4、指令命令将：数据自动写入数据库

php artisan operation:sync

//该命令获取到的参数
Array
(
    [api] => {POST} /admin/addAdmin 添加管理员
    [apiVersion] => 1.0.0
    [apiGrouP] => 管理员
    [apiParam] => {File} image 选填-头像
    [apiSuccessExample] => {json} Success-Response:
    [apiSampleRequest] => off
    [apiDescription] => * 【author】：浪里小白龙
)

数据库生成的结果：

image.png