README

介绍

基于 tw2066/dto tw2066/api-docs 框架改进而来，特别鸣谢tw2066/dto给的灵感

运行环境

• php >= 8.0
• lavarel 11.0

安装

composer require hesb/laravel-plus

配置工作

1. 在 web.php 添加代码

use Hesb\LaravelPlus\EasyCommand;

EasyCommand::register();

1. 从composer组件复制doc/api_docs.php到项目config目录下

使用说明

控制器配置

<?php

declare(strict_types=1);
namespace App\Http\Controllers\Api\Test;

use App\Http\Dto\Api\Test\TestBodyDto;
use App\Http\Dto\Api\Test\TestFormDto;
use App\Http\Dto\Api\Test\TestQueryDto;
use App\Http\Vo\DataSubmitVo;
use App\Http\Vo\Test\TestQueryVo;
use App\Logic\Api\User\UserLogic;
use Hesb\LaravelPlus\Annotation\Api;
use Hesb\LaravelPlus\Annotation\ApiOperation;
use Hesb\LaravelPlus\Annotation\ApiResponse;
use Hesb\LaravelPlus\Annotation\Contracts\RequestBody;
use Hesb\LaravelPlus\Annotation\Contracts\RequestFormData;
use Hesb\LaravelPlus\Annotation\Contracts\RequestQuery;
use Hesb\LaravelPlus\Annotation\Contracts\Valid;
use Hesb\LaravelPlus\Annotation\Controller;
use Hesb\LaravelPlus\Annotation\GetMapping;
use Hesb\LaravelPlus\Annotation\Inject;
use Hesb\LaravelPlus\Annotation\PostMapping;
use Hesb\LaravelPlus\Traits\Injectable;


#[Api(tags: '测试')]
#[Controller(prefix:"/api/api/test/test")]
class TestController
{
    #[ApiOperation('测试query')]
    #[GetMapping(path: 'query')]
    #[ApiResponse(TestQueryVo::class)]
    public function query(#[RequestQuery] #[Valid] TestQueryDto $dto){
        //逻辑层高处理对
        $params = get_object_vars($dto);
        $params['time'] = time();
        $params['token'] = csrf_token();
        //逻辑层返回数组
        //根据响应对象，约束响应数据
        return json_encode($params);
    }

    #[ApiOperation('测试body')]
    #[PostMapping(path: 'body')]
    #[ApiResponse(DataSubmitVo::class)]
    public function body(#[RequestBody] #[Valid] TestBodyDto $dto){
        //逻辑层返回数组
        $result = $this->logic->add($dto);
        //根据响应对象，约束响应数据
        return $result;
    }

    #[ApiOperation('测试form')]
    #[PostMapping(path: 'form')]
    #[ApiResponse(DataSubmitVo::class)]
    public function form(#[RequestFormData] #[Valid] TestFormDto $dto){
        var_dump($dto);
        $params = [];

        $params['time'] = time();
        //逻辑层返回数组
        //根据响应对象，约束响应数据
        return response()->json($params);
    }
}

创建简单DTO

#[ApiModel('query管理')]
class TestQueryDto
{
    #[ApiModelProperty('查询ID')]
    #[Required]
    public string $query_id;
}

创建复合DTO

#[ApiModel('body管理')]
class TestBodyDto
{
    #[ApiModelProperty(value:'用户信息',required: true)]
    #[Required]
    public UserDto $user;

    /**
     * @var \App\Http\Dto\Api\Test\TestBodyDetailDto []
     */
    #[ApiModelProperty(value:'明细列表',required: true)]
    public array $detail_list;

    #[ApiModelProperty(value:'创建日期')]
    #[Date]
//    #[After("2025-1-1")]
//    #[DateFormat("Y-m-d H:i:s")]
    public string $create_date;

//    #[ApiModelProperty(value:'body数组')]
//    #[Arr]
//    public array $arr;
//
//    #[ApiModelProperty(value:'url地址')]
//    #[Url]
//    public string $url;

//    #[ApiModelProperty(value:'ip地址')]
//    #[Ip]
//    public string $ip;

//    #[ApiModelProperty(value:'数字')]
//    #[Numeric]
//    public string $num;

//    #[ApiModelProperty(value:'服务协议')]
//    #[Accepted]
//    public string $accept;

//    #[ApiModelProperty(value:'字符串')]
//    #[Size(value:5)]
//    public string $str;
}

---

#[ApiModel('明细管理')]
class TestBodyDetailDto
{
    #[ApiModelProperty(value:'明细id',required: true)]
    #[Required]
    public string $detail_id;

}
---

#[ApiModel('用户管理')]
class UserDto
{
    #[ApiModelProperty(value:'昵称',required: true)]
    #[Required]
//    #[RequiredIf(['user.sex'=>'1'])]
//    #[Same("tc")]
    public string $nick_name;

    #[ApiModelProperty('手机号')]
    #[Regex(value:"/^(13[0-9]|14[579]|15[0-3,5-9]|16[6]|17[0135678]|18[0-9]|19[89])\d{8}$/")]
    public String $mobile;

    #[ApiModelProperty('邮箱')]
//    #[Email]
    public string $email;

    #[ApiModelProperty('年龄')]
//    #[Between(min:18,max:60)]
//    #[Min(18)]
    #[Required]
    public string $age;

    #[ApiModelProperty('性别: 1 男, 2 女')]
    #[In(['1','2'])]
//    #[NotIn(['1','2'])]
    public string $sex;
}

注意事项

1. 无论控制器和dto都要在类上加注解,否则无法扫描
2. 一个方法，不能同时注入RequestBody和RequestFormData,参照java springboot路由注解

效果

1. 通过命令生成swagger文档

   php artisan swagger:init
   

2. 访问 当前项目域名 + /swagger

图片如下

1. 根据dto配置自动校验 图片如下

参考https://gitee.com/hesb/laravel-test.git 配置