Java API端点文档生成器

请求方法：POST

端点路径：/api/v1/users

请求头

• Authorization: Bearer （需要具备 ADMIN 角色）
• Content-Type: application/json
• X-Idempotency-Key: （可选，用于幂等创建，建议每次创建请求使用全局唯一值）

请求参数（请求体：application/json） 字段说明（以下为字段格式与校验规则约束）：

• username: string
  • 长度 3–32
  • 仅允许字母、数字与点字符（.）
• email: string
  • 必须为有效邮箱地址，符合 RFC 5322 格式
• password: string
  • 长度 8–32
  • 必须至少包含一个数字与一个特殊字符
• roles: array of string
  • 元素取值枚举：USER、ADMIN、AUDITOR

请求体示例： { "username": "ling.han", "email": "ling@example.com", "password": "S3cure#Pass", "roles": ["USER", "AUDITOR"] }

成功响应

• 状态码：201 Created
• 响应头：
  • Location: /api/v1/users/{id}
• 响应体（application/json）：
  • 字段：
    • id: number（新用户ID）
    • username: string
    • email: string
    • createdAt: string（ISO 8601 UTC 时间戳，例如 2025-12-06T09:00:00Z）
  • 示例： { "id": 98421, "username": "ling.han", "email": "ling@example.com", "createdAt": "2025-12-06T09:00:00Z" }

错误响应

• 401 Unauthorized：未认证或令牌无效
• 409 Conflict：邮箱已存在
• 422 Unprocessable Entity：请求体验证失败（如用户名或密码不满足约束、邮箱格式不合法、roles 含无效枚举值等）

数据格式：JSON

cURL（成功创建） curl -X POST "https:///api/v1/users"
-H "Authorization: Bearer "
-H "Content-Type: application/json"
-H "X-Idempotency-Key: 2c2de54a-9a1e-4f4f-b3f2-7e8c0d88b3a2"
-d '{ "username":"ling.han", "email":"ling@example.com", "password":"S3cure#Pass", "roles":["USER","AUDITOR"] }'

成功响应示例： HTTP/1.1 201 Created Location: /api/v1/users/98421 Content-Type: application/json

{ "id": 98421, "username": "ling.han", "email": "ling@example.com", "createdAt": "2025-12-06T09:00:00Z" }

cURL（邮箱已存在导致 409） curl -X POST "https:///api/v1/users"
-H "Authorization: Bearer "
-H "Content-Type: application/json"
-d '{ "username":"any.user", "email":"existing@example.com", "password":"S3cure#Pass", "roles":["USER"] }'

可能响应： HTTP/1.1 409 Conflict

cURL（校验失败导致 422） curl -X POST "https:///api/v1/users"
-H "Authorization: Bearer "
-H "Content-Type: application/json"
-d '{ "username":"ab", // 小于 3 "email":"not-an-email", // 非 RFC5322 "password":"short", // 小于 8 且缺少数字/特殊字符 "roles":["UNKNOWN"] // 非法枚举值 }'

可能响应： HTTP/1.1 422 Unprocessable Entity

cURL（未认证导致 401） curl -X POST "https:///api/v1/users"
-H "Content-Type: application/json"
-d '{ ... }'

可能响应： HTTP/1.1 401 Unauthorized

• 新用户默认启用。
• 邮箱需全局唯一，冲突返回 409。
• 响应体不包含密码字段。
• createdAt 为 UTC 时间（后缀 Z）。

• username 边界值：2/3/32/33 字符；包含非法字符（如下划线、空格、中文、特殊符号）。
• email 合法/非法格式枚举用例（缺少 @、域不完整等）。
• password 边界值：7/8/32/33 字符；缺少数字或缺少特殊字符的组合用例。
• roles 包含非法值（非 USER/ADMIN/AUDITOR）的用例。
• 重复邮箱创建触发 409。
• 使用相同 X-Idempotency-Key 重试验证不重复创建。
• 未携带 Authorization 或携带无效令牌触发 401。

• Authorization: Bearer
• Content-Type: multipart/form-data

• folder: string
  • 含义：目标目录（如 avatars）
  • 是否必填：未明确，建议提供以便资源归档

• image: file（必填）
  • 约束：jpg/png，大小不超过 5MB
• altText: string（可选）
  • 约束：长度 0–120 字

• 状态码：201 Created
• 头部：Cache-Control: public, max-age=31536000
• 数据格式：application/json
• 响应体字段：
  • id: string，图片资源ID（例如 img_8f3c2）
  • url: string，CDN 可访问的原图 URL（含目录与日期路径）
  • width: number，原图宽度（像素）
  • height: number，原图高度（像素）
  • hash: string，格式为 sha256:
  • uploadedAt: string，上传时间（ISO 8601，UTC）

• 401 Unauthorized：未认证或令牌无效
• 413 Payload Too Large：文件体积超过限制
• 415 Unsupported Media Type：文件类型不支持（非 jpg/png）

cURL 示例（multipart 上传）

• 请求： curl -X POST "https://api.example.com/api/v1/assets/images?folder=avatars"
  -H "Authorization: Bearer "
  -H "Content-Type: multipart/form-data"
  -F "image=@avatar.png;type=image/png"
  -F "altText=User avatar"

• 成功响应示例（201）： { "id": "img_8f3c2", "url": "https://cdn.example.com/avatars/2025/12/06/xxx.png", "width": 1024, "height": 768, "hash": "sha256:ab12...", "uploadedAt": "2025-12-06T09:01:02Z" }

multipart 关键字段示例：

• key: image
• filename: avatar.png