做一次小小的备份,等会又删掉了
This commit is contained in:
432
specs/001-fiber-middleware-integration/contracts/api.yaml
Normal file
432
specs/001-fiber-middleware-integration/contracts/api.yaml
Normal file
@@ -0,0 +1,432 @@
|
||||
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"
|
||||
Reference in New Issue
Block a user