PHP code example of hyperf-plus / swagger

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

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

    

hyperf-plus / swagger example snippets

return [
    'enable' => true,
    'port' => 9501,
    'json_dir' => BASE_PATH . '/runtime/swagger/',
    'html' => '/swagger',
    'url' => '/swagger/openapi.json',
    'auto_generate' => true,
    'scan' => [
        'paths' => [BASE_PATH . '/app'],
    ],
];

use HPlus\Route\Annotation\ApiController;
use HPlus\Route\Annotation\GetApi;
use HPlus\Route\Annotation\PostApi;
use HPlus\Validate\Annotations\RequestValidation;
use HPlus\Swagger\Annotation\ApiDefinition;
use HPlus\Swagger\Annotation\ApiServer;

#[ApiController(tag: 'User Management')]
#[ApiServer(url: 'http://localhost:9501', description: 'Development Server')]
class UserController
{
    #[GetApi(summary: '获取用户列表', description: '支持分页和搜索')]
    #[RequestValidation(rules: [
        'page|页码' => 'integer|min:1|default:1',
        'size|每页数量' => 'integer|min:1|max:100|default:20',
        'keyword|搜索关键词' => 'string|max:50'
    ])]
    public function index() {}
    
    #[PostApi(summary: '创建用户')]
    #[RequestValidation(
        rules: [
            'username|用户名' => '

#[ApiDefinition(
    name: 'User',
    type: 'object',
    description: '用户模型',
    properties: [
        'id' => ['type' => 'integer', 'description' => '用户ID'],
        'username' => ['type' => 'string', 'description' => '用户名'],
        'email' => ['type' => 'string', 'format' => 'email'],
        'profile' => [
            'type' => 'object',
            'properties' => [
                'nickname' => ['type' => 'string'],
                'avatar' => ['type' => 'string', 'format' => 'uri']
            ]
        ],
        'status' => ['type' => 'string', 'enum' => ['active', 'inactive']],
        'created_at' => ['type' => 'string', 'format' => 'date-time']
    ],
    

#[ApiServer(
    url: 'https://api.example.com',
    description: 'Production Server',
    variables: [
        'version' => [
            'default' => 'v1',
            'enum' => ['v1', 'v2'],
            'description' => 'API Version'
        ]
    ]
)]

#[ApiCallback(
    name: 'onUserCreated',
    url: '{$request.body#/callback_url}',
    method: 'POST',
    requestBody: [
        'user_id' => 'integer',
        'event' => 'string'
    ]
)]

#[ApiLink(
    name: 'GetUserById',
    operationId: 'getUser',
    parameters: [
        'id' => '$response.body#/id'
    ]
)]

use HPlus\Route\Annotation\ApiResponse;
use HPlus\Route\Annotation\ApiResponseExample;

#[GetApi]
#[ApiResponse(code: 200, description: '成功')]
#[ApiResponseExample(
    code: 200,
    example: [
        'code' => 0,
        'message' => 'success',
        'data' => [
            'id' => 1,
            'username' => 'john_doe'
        ]
    ]
)]
public function show($id) {}

use HPlus\Route\Annotation\RequestBody;

#[PostApi]
#[RequestBody(
    description: '用户信息',
    rd' => 'secret123'
    ]
)]
public function create() {}

#[PostApi(summary: '上传头像')]
#[RequestValidation(
    rules: [
        'avatar' => '

// 全局安全配置
#[ApiController(security: true)]
class SecureController {}

// 方法级别配置
#[GetApi(security: true)]
public function privateData() {}

// 在配置文件中定义安全方案
'security_schemes' => [
    'bearerAuth' => [
        'type' => 'http',
        'scheme' => 'bearer',
        'bearerFormat' => 'JWT'
    ],
    'apiKey' => [
        'type' => 'apiKey',
        'in' => 'header',
        'name' => 'X-API-Key'
    ]
]

// 控制器级别标签
#[ApiController(tag: 'User Management', description: '用户管理相关接口')]

// 多标签支持
#[GetApi(tags: ['User', 'Admin'])]

// 标签描述（在配置中）
'tags' => [
    [
        'name' => 'User Management',
        'description' => '用户相关操作',
        'externalDocs' => [
            'description' => 'Find more info',
            'url' => 'https://example.com/docs/user'
        ]
    ]
]

return [
    'enable' => env('SWAGGER_ENABLE', true),
    'port' => 9501,
    'json_dir' => BASE_PATH . '/runtime/swagger/',
    'html' => '/swagger',
    'url' => '/swagger/openapi.json',
    'auto_generate' => true,
    
    // OpenAPI 基础信息
    'info' => [
        'title' => 'My API',
        'version' => '1.0.0',
        'description' => 'API Documentation',
        'termsOfService' => 'https://example.com/terms',
        'contact' => [
            'name' => 'API Support',
            'email' => '[email protected]',
            'url' => 'https://example.com/support'
        ],
        'license' => [
            'name' => 'MIT',
            'url' => 'https://opensource.org/licenses/MIT'
        ]
    ],
    
    // 服务器配置
    'servers' => [
        [
            'url' => 'http://localhost:9501',
            'description' => 'Development server'
        ],
        [
            'url' => 'https://api.example.com',
            'description' => 'Production server'
        ]
    ],
    
    // 安全方案
    'security_schemes' => [
        'bearerAuth' => [
            'type' => 'http',
            'scheme' => 'bearer',
            'bearerFormat' => 'JWT'
        ]
    ],
    
    // 扫描配置
    'scan' => [
        'paths' => [
            BASE_PATH . '/app/Controller',
        ],
        'ignore' => [
            BASE_PATH . '/app/Controller/AbstractController.php',
        ]
    ],
    
    // 外部文档
    'externalDocs' => [
        'description' => 'Find out more',
        'url' => 'https://example.com/docs'
    ]
];

'ui' => [
    'title' => 'My API Documentation',
    'favicon' => '/favicon.ico',
    'css' => '/custom.css',
    'js' => '/custom.js',
    'theme' => 'dark', // light, dark
    'tryItOutEnabled' => true,
    'docExpansion' => 'list', // none, list, full
    'defaultModelsExpandDepth' => 1,
    'persistAuthorization' => true,
]

   'cache' => [
       'enable' => true,
       'ttl' => 3600, // 缓存时间（秒）
       'dir' => BASE_PATH . '/runtime/swagger/cache/'
   ]
   

   'production' => [
       'enable' => false, // 生产环境关闭自动生成
       'cache_forever' => true, // 永久缓存
   ]
   

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

bash
# 生成文档
php bin/hyperf.php swagger:generate

# 清除缓存
php bin/hyperf.php swagger:clear

# 验证文档
php bin/hyperf.php swagger:validate

# 导出文档
php bin/hyperf.php swagger:export --format=yaml