1. Go to this page and download the library: Download tangwei/apidocs library. Choose the download type require.
2. Extract the ZIP file and open the index.php.
3. Add this code to the index.php.
<?php
require_once('vendor/autoload.php');
/* Start to develop here. Best regards https://php-download.com/ */
namespace App\Request;
use Hyperf\ApiDocs\Annotation\ApiModelProperty;
use Hyperf\DTO\Annotation\Validation\Required;
use Hyperf\DTO\Annotation\Validation\Integer;
use Hyperf\DTO\Annotation\Validation\Between;
class UserRequest
{
#[ApiModelProperty('用户名')]
#[Required]
public string $username;
#[ApiModelProperty('年龄')]
#[Required]
#[Integer]
#[Between(1, 120)]
public int $age;
#[ApiModelProperty('邮箱')]
public ?string $email = null;
}
namespace App\Controller;
use Hyperf\HttpServer\Annotation\Controller;
use Hyperf\HttpServer\Annotation\GetMapping;
use Hyperf\HttpServer\Annotation\PostMapping;
use Hyperf\ApiDocs\Annotation\Api;
use Hyperf\ApiDocs\Annotation\ApiOperation;
use Hyperf\DTO\Annotation\Contracts\RequestBody;
use Hyperf\DTO\Annotation\Contracts\RequestQuery;
use Hyperf\DTO\Annotation\Contracts\Valid;
use App\Request\UserRequest;
#[Controller(prefix: '/user')]
#[Api(tags: '用户管理', position: 1)]
class UserController
{
#[GetMapping(path: 'list')]
#[ApiOperation(summary: '获取用户列表')]
public function list(#[RequestQuery] #[Valid] UserRequest $request): array
{
return [
['id' => 1, 'username' => 'admin'],
['id' => 2, 'username' => 'user'],
];
}
#[PostMapping(path: 'create')]
#[ApiOperation(summary: '创建用户')]
public function create(#[RequestBody] #[Valid] UserRequest $request): array
{
return [
'id' => 1,
'username' => $request->username,
'age' => $request->age,
];
}
}
use Hyperf\ApiDocs\Annotation\ApiVariable;
class Page
{
public int $total;
#[ApiVariable]
public array $content;
public function __construct(array $content, int $total = 0)
{
$this->content = $content;
$this->total = $total;
}
}
#[ApiOperation('分页查询')]
#[GetMapping(path: 'page')]
#[ApiResponse(new Page([UserResponse::class]))]
public function page(#[RequestQuery] PageQuery $query): Page
{
// 返回分页数据
}
public function create(#[RequestBody] #[Valid] UserRequest $request)
{
// $request 自动填充 body 数据
}
public function list(#[RequestQuery] #[Valid] QueryRequest $request)
{
// $request 自动填充查询参数
}
#[ApiFormData(name: 'photo', format: 'binary')]
public function upload(#[RequestFormData] UploadRequest $formData)
{
$file = $this->request->file('photo');
// 处理文件上传
}
public function auth(#[RequestHeader] #[Valid] AuthHeader $header)
{
// $header 自动填充请求头数据
}
use Hyperf\DTO\Annotation\Validation\*;
class UserRequest
{
#[Required] // 必填
#[Max(50)] // 最大长度
public string $username;
#[Required]
#[Integer] // 整数
#[Between(1, 120)] // 范围
public int $age;
#[Email] // 邮箱格式
public ?string $email;
#[Url] // URL 格式
public ?string $website;
#[Regex('/^1[3-9]\d{9}$/')] // 正则验证
public ?string $mobile;
#[In(['male', 'female'])] // 枚举值
public ?string $gender;
#[Date] // 日期格式
public ?string $birthday;
}
public function create(#[RequestBody] #[Valid] UserRequest $request)
{
// 验证自动执行
}
// 支持 Laravel 风格的验证规则
#[Validation('idation('integer', customKey: 'ids.*')]
public array $ids;
namespace App\Validation;
use Attribute;
use Hyperf\DTO\Annotation\Validation\BaseValidation;
#[Attribute(Attribute::TARGET_PROPERTY)]
class Mobile extends BaseValidation
{
protected $rule = 'regex:/^1[3-9]\d{9}$/';
public function __construct(string $messages = '手机号格式错误')
{
parent::__construct($messages);
}
}
use App\Validation\Mobile;
class RegisterRequest
{
#[Required]
#[Mobile]
public string $phone;
}
/**
* @var Address[]
*/
#[ApiModelProperty('地址列表')]
public array $addresses;
/**
* @var int[]
*/
#[ApiModelProperty('ID 列表')]
public array $ids;
use Hyperf\DTO\Annotation\ArrayType;
#[ApiModelProperty('地址列表')]
#[ArrayType(Address::class)]
public array $addresses;
#[ApiModelProperty('标签列表')]
#[ArrayType('string')]
public array $tags;
class UserRequest
{
public string $name;
// 嵌套对象
#[ApiModelProperty('地址信息')]
public Address $address;
/**
* @var Address[]
*/
#[ApiModelProperty('多个地址')]
public array $addresses;
}
class Address
{
public string $province;
public string $city;
public string $street;
}
use Hyperf\DTO\Type\PhpType;
enum StatusEnum: int
{
case PENDING = 0;
case ACTIVE = 1;
case INACTIVE = 2;
}
class OrderRequest
{
#[ApiModelProperty('订单状态')]
public StatusEnum $status;
}
namespace App\DTO;
use Hyperf\ApiDocs\Annotation\ApiModelProperty;
use Hyperf\ApiDocs\Annotation\ApiVariable;
class GlobalResponse
{
#[ApiModelProperty('状态码')]
public int $code = 0;
#[ApiModelProperty('消息')]
public string $message = 'success';
#[ApiVariable]
#[ApiModelProperty('响应数据')]
public mixed $data = null;
}
use Hyperf\DTO\Annotation\Dto;
#[Dto]
class DemoQuery
{
}
use Hyperf\DTO\Annotation\Dto;
use Hyperf\DTO\Annotation\JSONField;
#[Dto]
class DemoQuery
{
#[ApiModelProperty('这是一个别名')]
#[JSONField('alias_name')]
#[Required]
public string $name;
}
use Hyperf\Serializer\SerializerFactory;
use Hyperf\Serializer\Serializer;
return [
Hyperf\Contract\NormalizerInterface::class => new SerializerFactory(Serializer::class),
];
/**
* @var User[]
*/
public array $users;
// 或
#[ArrayType(User::class)]
public array $users;