search

tw2066 / api-docs

MIT License
41 stars 16 forks source link

readme

PHP Swagger Api Docs

Latest Stable Version Total Downloads License

基于 Hyperf 框架的 swagger 文档生成组件，支持swoole/swow驱动

优点

使用须知

例子

请参考example目录

安装

composer require tangwei/apidocs

默认使用swagger-ui,可安装knife4j-ui(功能更强大) (可选)

composer require tangwei/knife4j-ui

使用

1. 发布配置文件

php bin/hyperf.php vendor:publish tangwei/apidocs

1.1 配置信息

config/autoload/api_docs.php

配置详情

```php use Hyperf\ApiDocs\DTO\GlobalResponse; use function Hyperf\Support\env; return [ /* |-------------------------------------------------------------------------- | 启动 swagger 服务 |-------------------------------------------------------------------------- | | false 将不会启动 swagger 服务 | */ 'enable' => env('APP_ENV') !== 'prod', /* |-------------------------------------------------------------------------- | 生成swagger文件格式 |-------------------------------------------------------------------------- | | 支持json和yaml | */ 'format' => 'json', /* |-------------------------------------------------------------------------- | 生成swagger文件路径 |-------------------------------------------------------------------------- */ 'output_dir' => BASE_PATH . '/runtime/container', /* |-------------------------------------------------------------------------- | 生成代理类路径 |-------------------------------------------------------------------------- */ 'proxy_dir' => BASE_PATH . '/runtime/container/proxy', /* |-------------------------------------------------------------------------- | 设置路由前缀 |-------------------------------------------------------------------------- */ 'prefix_url' => env('API_DOCS_PREFIX_URL', '/swagger'), /* |-------------------------------------------------------------------------- | 设置swagger资源路径,cdn资源 |-------------------------------------------------------------------------- */ 'prefix_swagger_resources' => 'https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.5.0', /* |-------------------------------------------------------------------------- | 设置全局返回的代理类 |-------------------------------------------------------------------------- | | 全局返回 如:[code=>200,data=>null] 格式,设置会后会全局生成对应文档 | 配合ApiVariable注解使用,示例参考GlobalResponse类 | 返回数据格式可以利用AOP统一返回 | */ // 'global_return_responses_class' => GlobalResponse::class, /* |-------------------------------------------------------------------------- | 替换验证属性 |-------------------------------------------------------------------------- | | 通过获取注解ApiModelProperty的值,来提供数据验证的提示信息 | */ 'validation_custom_attributes' => true, /* |-------------------------------------------------------------------------- | 设置DTO类默认值等级 |-------------------------------------------------------------------------- | | 设置:0 默认(不设置默认值) | 设置:1 简单类型会为设置默认值,复杂类型(带?)会设置null | - 简单类型默认值: int:0 float:0 string:'' bool:false array:[] mixed:null | 设置:2 (慎用)包含等级1且复杂类型(联合类型除外)会设置null | */ 'dto_default_value_level' => 0, /* |-------------------------------------------------------------------------- | 全局responses,映射到ApiResponse注解对象 |-------------------------------------------------------------------------- */ 'responses' => [ ['response' => 401, 'description' => 'Unauthorized'], ['response' => 500, 'description' => 'System error'], ], /* |-------------------------------------------------------------------------- | swagger 的基础配置 |-------------------------------------------------------------------------- | | 该属性会映射到OpenAPI对象 | */ 'swagger' => [ 'info' => [ 'title' => 'API DOC', 'version' => '0.1', 'description' => 'swagger api desc', ], 'servers' => [ [ 'url' => 'http://127.0.0.1:9501', 'description' => 'OpenApi host', ], ], 'components' => [ 'securitySchemes' => [ [ 'securityScheme' => 'Authorization', 'type' => 'apiKey', 'in' => 'header', 'name' => 'Authorization', ], ], ], 'security' => [ ['Authorization' => []], ], 'externalDocs' => [ 'description' => 'Find out more about Swagger', 'url' => 'https://github.com/tw2066/api-docs', ], ], ]; ```

2. 直接启动框架(需要有http服务)

php bin/hyperf.php start

[INFO] Swagger docs url at http://0.0.0.0:9501/swagger
[INFO] TaskWorker#1 started.
[INFO] Worker#0 started.
[INFO] HTTP Server listening at 0.0.0.0:9501

注解

命名空间:Hyperf\DTO\Annotation\Contracts

[RequestBody] 注解

public function add(#[RequestBody] DemoBodyRequest $request){}

[RequestQuery] 注解

public function add(#[RequestQuery] DemoQuery $request){}

[RequestFormData] 注解

public function fromData(#[RequestFormData] DemoFormData $formData){}
#[ApiFormData(name: 'photo', format: 'binary')]
public function add(#[RequestBody] DemoBodyRequest $request, #[RequestQuery] DemoQuery $query){}

[ApiSecurity] 注解

#[ApiSecurity('Authorization')]
public function getUserInfo(DemoToken $header){}

注意: 一个方法，不能同时注入RequestBody和RequestFormData

[ApiResponse] 注解

示例

控制器

#[Controller(prefix: '/demo')]
#[Api(tags: 'demo管理', position: 1)]
class DemoController extends AbstractController
{
    #[ApiOperation(summary: '查询')]
    #[PostMapping(path: 'index')]
    public function index(#[RequestQuery] #[Valid] DemoQuery $request): Contact
    {
        $contact = new Contact();
        $contact->name = $request->name;
        var_dump($request);
        return $contact;
    }

    #[PutMapping(path: 'add')]
    #[ApiOperation(summary: '提交body数据和get参数')]
    public function add(#[RequestBody] DemoBodyRequest $request, #[RequestQuery] DemoQuery $query)
    {
        var_dump($query);
        return json_encode($request, JSON_UNESCAPED_UNICODE);
    }

    #[PostMapping(path: 'fromData')]
    #[ApiOperation(summary: '表单提交')]
    #[ApiFormData(name: 'photo', type: 'file')]
    public function fromData(#[RequestFormData] DemoFormData $formData): bool
    {
        $file = $this->request->file('photo');
        var_dump($file);
        var_dump($formData);
        return true;
    }

    #[GetMapping(path: 'find/{id}/and/{in}')]
    #[ApiOperation('查询单体记录')]
    #[ApiHeader(name: 'test')]
    public function find(int $id, float $in): array
    {
        return ['$id' => $id, '$in' => $in];
    }
}

验证器

基于框架的验证

安装hyperf框架验证器hyperf/validation, 并配置(已安装忽略)

只需在控制器方法中加上 #[Valid] 注解

public function index(#[RequestQuery] #[Valid] DemoQuery $request){}
class DemoQuery
{
    #[ApiModelProperty('名称')]
    #[Required]
    #[Max(5)]
    #[In(['qq','aa'])]
    public string $name;

    #[ApiModelProperty('正则')]
    #[Str]
    #[Regex('/^.+@.+$/i')]
    #[StartsWith('aa,bb')]
    #[Max(10)]
    public string $email;

    #[ApiModelProperty('数量')]
    #[Required]
    #[Integer]
    #[Between(1,5)]
    public int $num;
}

自定义注解验证

注解的验证支持框架所有验证, 组件提供了常用的注解用于验证

  1. 使用自定义验证注解, 创建注解类继承Hyperf\DTO\Annotation\Validation\BaseValidation
  2. 重写$rule属性或getRule方法
//示例
#[Attribute(Attribute::TARGET_PROPERTY)]
class Image extends BaseValidation
{
    protected $rule = 'image';
}

验证器Validation

  1. 大家都习惯了框架的required|date|after:start_date写法
//可以通过Validation实现
#[Validation('required|date|after:start_date')]
  1. 需要支持数组里面是int数据情况 'intArr.*' => 'integer'的情况
//可以通过Validation中customKey来自定义key实现
#[Validation('integer', customKey: 'intArr.*')]
public array $intArr;

注意

数组类型的问题

PHP原生暂不支持int[]或Class[]类型, 使用示例

    /**
     * class类型映射数组.
     * @var \App\DTO\Address[]
     */
    #[ApiModelProperty('地址')]
    public array $addressArr;

    /**
     * 简单类型映射数组.
     * @var int[]
     */
    #[ApiModelProperty('int类型的数组')]
    public array $intArr;

    /**
     * 通过注解映射数组.
     */
    #[ApiModelProperty('string类型的数组')]
    #[ArrayType('string')]
    public array $stringArr;

AutoController注解

控制器中使用AutoController注解,只收集了POST方法

DTO数据映射

api-docs引入到dto组件

注解

Dto注解

标记为dto类

use Hyperf\DTO\Annotation\Dto;

#[Dto]
class DemoQuery
{
}

JSONField注解

用于设置属性的别名

use Hyperf\DTO\Annotation\Dto;
use Hyperf\DTO\Annotation\JSONField;

#[Dto]
class DemoQuery
{
    #[ApiModelProperty('这是一个别名')]
    #[JSONField('alias_name')]
    #[Required]
    public string $name;   
}

RPC 返回PHP对象

aspects.php中配置

return [
\Hyperf\DTO\Aspect\ObjectNormalizerAspect::class
]

当框架导入 symfony/serializer (^5.0) 和 symfony/property-access (^5.0) 后，并在 dependencies.php 中配置一下映射关系


use Hyperf\Serializer\SerializerFactory;
use Hyperf\Serializer\Serializer;

return [ Hyperf\Contract\NormalizerInterface::class => new SerializerFactory(Serializer::class), ];


## Phar 打包器

```shell
# 1.启动生成代理类和注解缓存
php bin/hyperf.php start
# 2.打包
php bin/hyperf.php phar:build

Swagger界面

hMvJnQ

PHP Accessor

生成类访问器（Getter & Setter）

推荐使用free2one/hyperf-php-accessor