datahub/backend/app/OpenApiSpec.php

<?php

declare(strict_types=1);

namespace App;

use OpenApi\Attributes as OA;

#[OA\Info(
    version: '1.0.0',
    title: 'Datahub API',
    description: 'Datahub API documentation'
)]
#[OA\Server(url: '/api/v1', description: 'API v1')]
#[OA\SecurityScheme(
    securityScheme: 'bearerAuth',
    type: 'http',
    scheme: 'bearer',
    bearerFormat: 'JWT'
)]
#[OA\SecurityScheme(
    securityScheme: 'apiKeyAuth',
    type: 'apiKey',
    in: 'header',
    name: 'X-API-Key'
)]
#[OA\Schema(
    schema: 'ApiResponse',
    type: 'object',
    properties: [
        new OA\Property(property: 'code', type: 'integer', example: 0),
        new OA\Property(property: 'message', type: 'string', example: 'success'),
        new OA\Property(property: 'data', type: 'object', nullable: true),
    ]
)]
#[OA\Schema(
    schema: 'PaginatedData',
    type: 'object',
    properties: [
        new OA\Property(property: 'items', type: 'array', items: new OA\Items()),
        new OA\Property(property: 'total', type: 'integer', example: 0),
        new OA\Property(property: 'page', type: 'integer', example: 1),
        new OA\Property(property: 'per_page', type: 'integer', example: 15),
    ]
)]
#[OA\Schema(
    schema: 'ErrorResponse',
    type: 'object',
    properties: [
        new OA\Property(property: 'code', type: 'integer', example: 400),
        new OA\Property(property: 'message', type: 'string', example: 'Bad request'),
        new OA\Property(property: 'data', type: 'object', nullable: true),
    ]
)]
#[OA\Schema(
    schema: 'MqQueueInfo',
    type: 'object',
    description: '单个队列的状态信息',
    properties: [
        new OA\Property(property: 'queue', type: 'string', example: 'orders.queue', description: '队列名称'),
        new OA\Property(property: 'messages', description: '消息数量（异常时为 N/A）', oneOf: [new OA\Schema(type: 'integer'), new OA\Schema(type: 'string')], example: 5),
        new OA\Property(property: 'consumers', description: '消费者数量（异常时为 N/A）', oneOf: [new OA\Schema(type: 'integer'), new OA\Schema(type: 'string')], example: 1),
        new OA\Property(property: 'status', type: 'string', enum: ['high_load', 'processing', 'active', 'empty', 'error'], example: 'active', description: '队列状态'),
    ]
)]
#[OA\Schema(
    schema: 'MqQueueStatus',
    type: 'object',
    description: '消息队列全量状态',
    properties: [
        new OA\Property(property: 'business_queues', type: 'array', items: new OA\Items(ref: '#/components/schemas/MqQueueInfo'), description: '业务队列列表'),
        new OA\Property(property: 'retry_queues', type: 'array', items: new OA\Items(ref: '#/components/schemas/MqQueueInfo'), description: '重试队列列表'),
        new OA\Property(property: 'error_queue', ref: '#/components/schemas/MqQueueInfo', description: '错误队列（筛选时为空数组）'),
        new OA\Property(property: 'summary', properties: [
            new OA\Property(property: 'total_messages', type: 'integer', example: 7, description: '消息总数'),
            new OA\Property(property: 'total_consumers', type: 'integer', example: 1, description: '消费者总数'),
        ], type: 'object', description: '汇总统计'),
        new OA\Property(property: 'fetched_at', type: 'string', format: 'date-time', example: '2026-03-13 12:00:00', description: '数据获取时间'),
    ]
)]
class OpenApiSpec
{
}