433 lines
12 KiB
YAML
433 lines
12 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: 君鸿卡管系统 API
|
|
description: |
|
|
Card Management System API with unified response format and middleware integration.
|
|
|
|
## Unified Response Format
|
|
|
|
All API endpoints return responses in the following unified format:
|
|
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"data": {},
|
|
"msg": "success",
|
|
"timestamp": "2025-11-10T15:30:45Z"
|
|
}
|
|
```
|
|
|
|
## Error Codes
|
|
|
|
| Code | HTTP Status | Description (EN) | Description (ZH) |
|
|
|------|-------------|------------------|------------------|
|
|
| 0 | 200 | Success | 成功 |
|
|
| 1000 | 500 | Internal server error | 内部服务器错误 |
|
|
| 1001 | 401 | Missing authentication token | 缺失认证令牌 |
|
|
| 1002 | 401 | Invalid or expired token | 令牌无效或已过期 |
|
|
| 1003 | 429 | Too many requests | 请求过于频繁 |
|
|
| 1004 | 503 | Authentication service unavailable | 认证服务不可用 |
|
|
|
|
## Authentication
|
|
|
|
Protected endpoints require a valid authentication token in the request header:
|
|
|
|
```
|
|
token: your-auth-token-here
|
|
```
|
|
|
|
## Request Tracing
|
|
|
|
Every response includes an `X-Request-ID` header containing a unique UUID v4 identifier for request tracing and correlation.
|
|
|
|
version: 0.0.1
|
|
contact:
|
|
name: API Support
|
|
email: support@example.com
|
|
|
|
servers:
|
|
- url: http://localhost:3000
|
|
description: Development server
|
|
- url: https://api-staging.example.com
|
|
description: Staging server
|
|
- url: https://api.example.com
|
|
description: Production server
|
|
|
|
tags:
|
|
- name: health
|
|
description: Health check and system status
|
|
- name: users
|
|
description: User management (example endpoints)
|
|
|
|
paths:
|
|
/health:
|
|
get:
|
|
tags:
|
|
- health
|
|
summary: Health check endpoint
|
|
description: Returns system health status. No authentication required.
|
|
operationId: getHealth
|
|
responses:
|
|
'200':
|
|
description: System is healthy
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/X-Request-ID'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SuccessResponse'
|
|
example:
|
|
code: 0
|
|
data:
|
|
status: "healthy"
|
|
timestamp: "2025-11-10T15:30:45Z"
|
|
msg: "success"
|
|
timestamp: "2025-11-10T15:30:45Z"
|
|
|
|
/api/v1/users:
|
|
get:
|
|
tags:
|
|
- users
|
|
summary: List users (example endpoint)
|
|
description: |
|
|
Returns a list of users. Demonstrates middleware integration:
|
|
- Request ID generation
|
|
- Authentication (keyauth)
|
|
- Access logging
|
|
- Rate limiting (if enabled)
|
|
operationId: listUsers
|
|
security:
|
|
- TokenAuth: []
|
|
parameters:
|
|
- name: page
|
|
in: query
|
|
description: Page number (1-indexed)
|
|
schema:
|
|
type: integer
|
|
default: 1
|
|
minimum: 1
|
|
- name: page_size
|
|
in: query
|
|
description: Number of items per page
|
|
schema:
|
|
type: integer
|
|
default: 20
|
|
minimum: 1
|
|
maximum: 100
|
|
responses:
|
|
'200':
|
|
description: Successfully retrieved user list
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/X-Request-ID'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SuccessResponse'
|
|
example:
|
|
code: 0
|
|
data:
|
|
- id: "user-123"
|
|
name: "John Doe"
|
|
email: "john@example.com"
|
|
- id: "user-456"
|
|
name: "Jane Smith"
|
|
email: "jane@example.com"
|
|
msg: "success"
|
|
timestamp: "2025-11-10T15:30:45Z"
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'429':
|
|
$ref: '#/components/responses/TooManyRequests'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
'503':
|
|
$ref: '#/components/responses/ServiceUnavailable'
|
|
|
|
post:
|
|
tags:
|
|
- users
|
|
summary: Create user (example endpoint)
|
|
description: Creates a new user. Requires authentication.
|
|
operationId: createUser
|
|
security:
|
|
- TokenAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- name
|
|
- email
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: "John Doe"
|
|
email:
|
|
type: string
|
|
format: email
|
|
example: "john@example.com"
|
|
responses:
|
|
'200':
|
|
description: User created successfully
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/X-Request-ID'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SuccessResponse'
|
|
example:
|
|
code: 0
|
|
data:
|
|
id: "user-789"
|
|
name: "John Doe"
|
|
email: "john@example.com"
|
|
created_at: "2025-11-10T15:30:45Z"
|
|
msg: "success"
|
|
timestamp: "2025-11-10T15:30:45Z"
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'429':
|
|
$ref: '#/components/responses/TooManyRequests'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
|
|
/api/v1/users/{id}:
|
|
get:
|
|
tags:
|
|
- users
|
|
summary: Get user by ID (example endpoint)
|
|
description: Returns a single user by ID. Requires authentication.
|
|
operationId: getUserByID
|
|
security:
|
|
- TokenAuth: []
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
description: User ID
|
|
schema:
|
|
type: string
|
|
example: "user-123"
|
|
responses:
|
|
'200':
|
|
description: Successfully retrieved user
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/X-Request-ID'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SuccessResponse'
|
|
example:
|
|
code: 0
|
|
data:
|
|
id: "user-123"
|
|
name: "John Doe"
|
|
email: "john@example.com"
|
|
created_at: "2025-11-10T15:00:00Z"
|
|
msg: "success"
|
|
timestamp: "2025-11-10T15:30:45Z"
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: User not found
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/X-Request-ID'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
code: 2001
|
|
data: null
|
|
msg: "User not found"
|
|
timestamp: "2025-11-10T15:30:45Z"
|
|
'429':
|
|
$ref: '#/components/responses/TooManyRequests'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
|
|
components:
|
|
securitySchemes:
|
|
TokenAuth:
|
|
type: apiKey
|
|
in: header
|
|
name: token
|
|
description: Authentication token stored in Redis (token → user ID mapping)
|
|
|
|
headers:
|
|
X-Request-ID:
|
|
description: Unique request identifier (UUID v4) for tracing and correlation
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
example: "550e8400-e29b-41d4-a716-446655440000"
|
|
|
|
schemas:
|
|
SuccessResponse:
|
|
type: object
|
|
required:
|
|
- code
|
|
- data
|
|
- msg
|
|
- timestamp
|
|
properties:
|
|
code:
|
|
type: integer
|
|
description: Application status code (0 = success)
|
|
example: 0
|
|
data:
|
|
description: Response data (object, array, or null)
|
|
oneOf:
|
|
- type: object
|
|
- type: array
|
|
- type: 'null'
|
|
msg:
|
|
type: string
|
|
description: Human-readable message
|
|
example: "success"
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
description: Response timestamp in ISO 8601 format (RFC3339)
|
|
example: "2025-11-10T15:30:45Z"
|
|
|
|
ErrorResponse:
|
|
type: object
|
|
required:
|
|
- code
|
|
- data
|
|
- msg
|
|
- timestamp
|
|
properties:
|
|
code:
|
|
type: integer
|
|
description: Application error code (non-zero)
|
|
example: 1002
|
|
data:
|
|
type: 'null'
|
|
description: Always null for error responses
|
|
example: null
|
|
msg:
|
|
type: string
|
|
description: Error message (bilingual support)
|
|
example: "Invalid or expired token"
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
description: Response timestamp in ISO 8601 format (RFC3339)
|
|
example: "2025-11-10T15:30:45Z"
|
|
|
|
responses:
|
|
Unauthorized:
|
|
description: Authentication failed
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/X-Request-ID'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
examples:
|
|
missing_token:
|
|
summary: Missing token
|
|
value:
|
|
code: 1001
|
|
data: null
|
|
msg: "Missing authentication token"
|
|
timestamp: "2025-11-10T15:30:45Z"
|
|
invalid_token:
|
|
summary: Invalid or expired token
|
|
value:
|
|
code: 1002
|
|
data: null
|
|
msg: "Invalid or expired token"
|
|
timestamp: "2025-11-10T15:30:45Z"
|
|
|
|
TooManyRequests:
|
|
description: Rate limit exceeded
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/X-Request-ID'
|
|
Retry-After:
|
|
description: Number of seconds to wait before retrying
|
|
schema:
|
|
type: integer
|
|
example: 60
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
code: 1003
|
|
data: null
|
|
msg: "Too many requests"
|
|
timestamp: "2025-11-10T15:30:45Z"
|
|
|
|
InternalServerError:
|
|
description: Internal server error
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/X-Request-ID'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
code: 1000
|
|
data: null
|
|
msg: "Internal server error"
|
|
timestamp: "2025-11-10T15:30:45Z"
|
|
|
|
ServiceUnavailable:
|
|
description: Service unavailable (e.g., Redis down)
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/X-Request-ID'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
code: 1004
|
|
data: null
|
|
msg: "Authentication service unavailable"
|
|
timestamp: "2025-11-10T15:30:45Z"
|
|
|
|
examples:
|
|
SuccessWithObject:
|
|
summary: Success response with object data
|
|
value:
|
|
code: 0
|
|
data:
|
|
id: "user-123"
|
|
name: "John Doe"
|
|
msg: "success"
|
|
timestamp: "2025-11-10T15:30:45Z"
|
|
|
|
SuccessWithArray:
|
|
summary: Success response with array data
|
|
value:
|
|
code: 0
|
|
data:
|
|
- id: "1"
|
|
name: "Item 1"
|
|
- id: "2"
|
|
name: "Item 2"
|
|
msg: "success"
|
|
timestamp: "2025-11-10T15:30:45Z"
|
|
|
|
SuccessWithNull:
|
|
summary: Success response with null data
|
|
value:
|
|
code: 0
|
|
data: null
|
|
msg: "Operation completed"
|
|
timestamp: "2025-11-10T15:30:45Z"
|