PHP code example of lujihong / hyperf-swagger

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

lujihong / hyperf-swagger example snippets

return [
    // enable false 将不会生成 swagger 文件
    'enable' => env('APP_ENV') !== 'prod',
    // swagger 配置的输出文件
    // 当你有多个 http server 时, 可以在输出文件的名称中增加 {server} 字面变量
    // 比如 /public/swagger/swagger_{server}.json
    'output_file' => BASE_PATH . '/public/swagger/swagger.json',
    // 忽略的hook, 非必须 用于忽略符合条件的接口, 将不会输出到上定义的文件中
    'ignore' => function ($controller, $action) {
        return false;
    },
    // 自定义验证器错误码、错误描述字段
    'error_code' => 400,
    'http_status_code' => 200,
    'field_error_code' => 'code',
    'field_error_message' => 'message',
    'exception_enable' => false,
    // swagger 的基础配置
    'swagger' => [
        'swagger' => '2.0',
        'info' => [
            'description' => 'hyperf swagger api desc',
            'version' => '1.0.0',
            'title' => 'HYPERF API DOC',
        ],
        'host' => 'apidoc.cc',
        'schemes' => ['http', 'https'],
    ],
    'templates' => [
        // {template} 字面变量  替换 schema 内容
//        // 默认 成功 返回
//        'success' => [
//            "code|code"    => '0',
//            "result"  => '{template}',
//            "message|message" => 'Success',
//        ],
//        // 分页
//        'page' => [
//            "code|code"    => '0',
//            "result"  => [
//                'pageSize' => 10,
//                'total' => 1,
//                'totalPage' => 1,
//                'list' => '{template}'
//            ],
//            "message|message" => 'Success',
//        ],
    ],
    // golbal 节点 为全局性的 参数配置
    // 跟注解相同, 支持 header, path, query, body, formData
    // 子项为具体定义
    // 模式一: [ key => rule ]
    // 模式二: [ [key, rule, defautl, description] ]
    'global' => [
        // 'header' => [
        //     "x-token|验签" => "

// config/autoload/middlewares.php

Hyperf\Apidoc\Middleware\ApiValidationMiddleware::class

/**
 * @ApiVersion(version="v1")
 * @ApiServer(name="http")
 */
class UserController {} 

@ApiResponse(code="0", description="删除成功", schema={"id|这里是ID":1})
@ApiResponse(code="0", description="删除成功", schema={"$ref": "ExampleResponse"})

declare(strict_types=1);
namespace App\Test;

use Hyperf\Apidoc\Annotation\ValidationRule;

/**
 * 在任意位置创建规则类
 */

#[ValidationRule()]
class TestRute
{
    /**
     * @param $attribute 属性
     * @param $value 属性值
     * @return bool|string 校验错误则返回错误信息, 正确则返回 true
     */
    public function test($attribute, $value)
    {
        return '这是test';
    }
}

declare(strict_types=1);
namespace App\Controller;

use Hyperf\Apidoc\Annotation\ApiController;
use Hyperf\Apidoc\Annotation\ApiResponse;
use Hyperf\Apidoc\Annotation\ApiVersion;
use Hyperf\Apidoc\Annotation\Body;
use Hyperf\Apidoc\Annotation\DeleteApi;
use Hyperf\Apidoc\Annotation\FormData;
use Hyperf\Apidoc\Annotation\GetApi;
use Hyperf\Apidoc\Annotation\Header;
use Hyperf\Apidoc\Annotation\PostApi;
use Hyperf\Apidoc\Annotation\RequestApi;
use Hyperf\Apidoc\Annotation\Query;
use Hyperf\HttpServer\Contract\RequestInterface;
use Hyperf\Utils\ApplicationContext;

/**
 * @ApiVersion(version="v1")
 * @ApiController(tag="demo管理", description="demo的新增/修改/删除接口")
 * @ApiDefinitions({
 *  @ApiDefinition(name="DemoOkResponse", properties={
 *     "code|响应码": 200,
 *     "msg|响应信息": "ok",
 *     "data|响应数据": {"$ref": "DemoInfoData"}
 *  }),
 *  @ApiDefinition(name="DemoInfoData", properties={
 *     "userInfo|用户数据": {"$ref": "DemoInfoDetail"}
 *  }),
 *  @ApiDefinition(name="DemoInfoDetail", properties={
 *     "id|用户ID": 1,
 *     "mobile|用户手机号": { "default": "13545321231", "type": "string" },
 *     "nickname|用户昵称": "nickname",
 *     "avatar": { "default": "avatar", "type": "string", "description": "用户头像" },
 *  })
 * })
 */
class DemoController extends AuthController
{

    /**
     * 默认不定义 methods 默认值 post, get, put, delete 不区分大小写
     * @RequestApi(path="/test", summary="测试", methods="post, get, put, delete")
     * @ApiResponse(code="200", description="ok", schema={{
     *     "a|aa": {{
     *          "a|aaa":"b","c|ccc":5.2
     *      }},
     *     "b|ids": {1,2,3},
     *     "c|strings": {"a","b","c"},
     *     "d|dd": {"a":"b","c":"d"},
     *     "e|ee": "f"
     * }})
     */
    public function test()
    {
    
    }

    /**
     * @PostApi(path="/demo", description="添加一个用户")
     * @Header(key="token|接口访问凭证", rule="urn [
            'code' => 0,
            'id'   => 1,
            'name' => '张三',
            'age'  => 1,
        ];
    }

    /**
     * schema中可以指定$ref属性引用定义好的definition
     * @GetApi(path="/demo/info", description="获取用户详情")
     * @Query(key="id", rule="

bash
php bin/hyperf.php vendor:publish lujihong/hyperf-swagger

# hyperf/validation 的依赖发布

php bin/hyperf.php vendor:publish hyperf/translation

php bin/hyperf.php vendor:publish hyperf/validation

bash
php bin/hyperf.php apidoc:ui

php bin/hyperf.php apidoc:ui --port 8888