From 4b105727940ce92b51b099ced10e3c7ff25c998e Mon Sep 17 00:00:00 2001
From: Nick Zeng <Nick.Zeng@wpic.co>
Date: Fri, 6 Mar 2026 16:55:46 +0800
Subject: [PATCH] update openapi

---
 backend/app/Model/User.php  | 15 ++++++++++
 backend/app/OpenApiSpec.php | 57 +++++++++++++++++++++++++++++++++++++
 backend/composer.json       |  3 +-
 3 files changed, 74 insertions(+), 1 deletion(-)
 create mode 100644 backend/app/OpenApiSpec.php

diff --git a/backend/app/Model/User.php b/backend/app/Model/User.php
index 4e75711..1802b6f 100644
--- a/backend/app/Model/User.php
+++ b/backend/app/Model/User.php
@@ -6,6 +6,7 @@ namespace App\Model;
 
 use Hyperf\Database\Model\Relations\HasMany;
 use Hyperf\DbConnection\Model\Model;
+use OpenApi\Attributes as OA;
 use Qbhy\HyperfAuth\Authenticatable;
 
 /**
@@ -20,6 +21,20 @@ use Qbhy\HyperfAuth\Authenticatable;
  * @property \Carbon\Carbon $created_at
  * @property \Carbon\Carbon $updated_at
  */
+#[OA\Schema(
+    schema: 'User',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'id', type: 'integer', example: 1),
+        new OA\Property(property: 'username', type: 'string', example: 'user_1234'),
+        new OA\Property(property: 'email', type: 'string', example: 'user@example.com'),
+        new OA\Property(property: 'status', type: 'integer', example: 1),
+        new OA\Property(property: 'ext', type: 'object', nullable: true, example: ['nickname' => 'user']),
+        new OA\Property(property: 'refresh_token_expires_at', type: 'string', format: 'date-time', nullable: true),
+        new OA\Property(property: 'created_at', type: 'string', format: 'date-time'),
+        new OA\Property(property: 'updated_at', type: 'string', format: 'date-time'),
+    ]
+)]
 class User extends Model implements Authenticatable
 {
     /**
diff --git a/backend/app/OpenApiSpec.php b/backend/app/OpenApiSpec.php
new file mode 100644
index 0000000..056af09
--- /dev/null
+++ b/backend/app/OpenApiSpec.php
@@ -0,0 +1,57 @@
+<?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),
+    ]
+)]
+class OpenApiSpec
+{
+}
diff --git a/backend/composer.json b/backend/composer.json
index 0c77884..0c07597 100644
--- a/backend/composer.json
+++ b/backend/composer.json
@@ -29,7 +29,8 @@
         "hyperf/logger": "~3.1.0",
         "hyperf/memory": "~3.1.0",
         "hyperf/process": "~3.1.0",
-        "hyperf/rate-limit": "^3.1"
+        "hyperf/rate-limit": "^3.1",
+        "zircote/swagger-php": "^6.0"
     },
     "require-dev": {
         "friendsofphp/php-cs-fixer": "^3.0",