forked from datawhale/whale-town-end
docs：创建完整的API接口文档
- 创建详细的API接口说明文档 - 提供OpenAPI 3.0规范文件 - 创建Postman测试集合 - 添加API文档使用指南
This commit is contained in:
moyin
568
docs/api/openapi.yaml
Normal file
568
docs/api/openapi.yaml
Normal file
@@ -0,0 +1,568 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: Pixel Game Server - Auth API
|
||||
description: 像素游戏服务器用户认证API接口文档
|
||||
version: 1.0.0
|
||||
contact:
|
||||
name: API Support
|
||||
email: support@example.com
|
||||
license:
|
||||
name: MIT
|
||||
url: https://opensource.org/licenses/MIT
|
||||
|
||||
servers:
|
||||
- url: http://localhost:3000
|
||||
description: 开发环境
|
||||
|
||||
tags:
|
||||
- name: auth
|
||||
description: 用户认证相关接口
|
||||
|
||||
paths:
|
||||
/auth/login:
|
||||
post:
|
||||
tags:
|
||||
- auth
|
||||
summary: 用户登录
|
||||
description: 支持用户名、邮箱或手机号登录
|
||||
operationId: login
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LoginDto'
|
||||
example:
|
||||
identifier: testuser
|
||||
password: password123
|
||||
responses:
|
||||
'200':
|
||||
description: 登录成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LoginResponse'
|
||||
example:
|
||||
success: true
|
||||
data:
|
||||
user:
|
||||
id: "1"
|
||||
username: testuser
|
||||
nickname: 测试用户
|
||||
email: test@example.com
|
||||
phone: "+8613800138000"
|
||||
avatar_url: https://example.com/avatar.jpg
|
||||
role: 1
|
||||
created_at: "2025-12-17T10:00:00.000Z"
|
||||
access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
refresh_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
is_new_user: false
|
||||
message: 登录成功
|
||||
message: 登录成功
|
||||
'400':
|
||||
description: 请求参数错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
'401':
|
||||
description: 用户名或密码错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
|
||||
/auth/register:
|
||||
post:
|
||||
tags:
|
||||
- auth
|
||||
summary: 用户注册
|
||||
description: 创建新用户账户
|
||||
operationId: register
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/RegisterDto'
|
||||
example:
|
||||
username: newuser
|
||||
password: password123
|
||||
nickname: 新用户
|
||||
email: newuser@example.com
|
||||
phone: "+8613800138001"
|
||||
responses:
|
||||
'201':
|
||||
description: 注册成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/RegisterResponse'
|
||||
'400':
|
||||
description: 请求参数错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
'409':
|
||||
description: 用户名或邮箱已存在
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
|
||||
/auth/github:
|
||||
post:
|
||||
tags:
|
||||
- auth
|
||||
summary: GitHub OAuth登录
|
||||
description: 使用GitHub账户登录或注册
|
||||
operationId: githubOAuth
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/GitHubOAuthDto'
|
||||
example:
|
||||
github_id: "12345678"
|
||||
username: octocat
|
||||
nickname: The Octocat
|
||||
email: octocat@github.com
|
||||
avatar_url: https://github.com/images/error/octocat_happy.gif
|
||||
responses:
|
||||
'200':
|
||||
description: GitHub登录成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/GitHubOAuthResponse'
|
||||
'400':
|
||||
description: 请求参数错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
'401':
|
||||
description: GitHub认证失败
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
|
||||
/auth/forgot-password:
|
||||
post:
|
||||
tags:
|
||||
- auth
|
||||
summary: 发送密码重置验证码
|
||||
description: 向用户邮箱或手机发送密码重置验证码
|
||||
operationId: forgotPassword
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ForgotPasswordDto'
|
||||
example:
|
||||
identifier: test@example.com
|
||||
responses:
|
||||
'200':
|
||||
description: 验证码发送成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ForgotPasswordResponse'
|
||||
'400':
|
||||
description: 请求参数错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
'404':
|
||||
description: 用户不存在
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
|
||||
/auth/reset-password:
|
||||
post:
|
||||
tags:
|
||||
- auth
|
||||
summary: 重置密码
|
||||
description: 使用验证码重置用户密码
|
||||
operationId: resetPassword
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ResetPasswordDto'
|
||||
example:
|
||||
identifier: test@example.com
|
||||
verification_code: "123456"
|
||||
new_password: newpassword123
|
||||
responses:
|
||||
'200':
|
||||
description: 密码重置成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CommonResponse'
|
||||
'400':
|
||||
description: 请求参数错误或验证码无效
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
'404':
|
||||
description: 用户不存在
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
|
||||
/auth/change-password:
|
||||
put:
|
||||
tags:
|
||||
- auth
|
||||
summary: 修改密码
|
||||
description: 用户修改自己的密码（需要提供旧密码）
|
||||
operationId: changePassword
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ChangePasswordDto'
|
||||
example:
|
||||
user_id: "1"
|
||||
old_password: oldpassword123
|
||||
new_password: newpassword123
|
||||
responses:
|
||||
'200':
|
||||
description: 密码修改成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CommonResponse'
|
||||
'400':
|
||||
description: 请求参数错误或旧密码不正确
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
'404':
|
||||
description: 用户不存在
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
|
||||
components:
|
||||
schemas:
|
||||
LoginDto:
|
||||
type: object
|
||||
required:
|
||||
- identifier
|
||||
- password
|
||||
properties:
|
||||
identifier:
|
||||
type: string
|
||||
description: 登录标识符，支持用户名、邮箱或手机号
|
||||
minLength: 1
|
||||
maxLength: 100
|
||||
example: testuser
|
||||
password:
|
||||
type: string
|
||||
description: 用户密码
|
||||
minLength: 1
|
||||
maxLength: 128
|
||||
example: password123
|
||||
|
||||
RegisterDto:
|
||||
type: object
|
||||
required:
|
||||
- username
|
||||
- password
|
||||
- nickname
|
||||
properties:
|
||||
username:
|
||||
type: string
|
||||
description: 用户名，只能包含字母、数字和下划线
|
||||
minLength: 1
|
||||
maxLength: 50
|
||||
pattern: '^[a-zA-Z0-9_]+$'
|
||||
example: testuser
|
||||
password:
|
||||
type: string
|
||||
description: 密码，必须包含字母和数字，长度8-128字符
|
||||
minLength: 8
|
||||
maxLength: 128
|
||||
pattern: '^(?=.*[a-zA-Z])(?=.*\d)'
|
||||
example: password123
|
||||
nickname:
|
||||
type: string
|
||||
description: 用户昵称
|
||||
minLength: 1
|
||||
maxLength: 50
|
||||
example: 测试用户
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
description: 邮箱地址（可选）
|
||||
example: test@example.com
|
||||
phone:
|
||||
type: string
|
||||
description: 手机号码（可选）
|
||||
example: "+8613800138000"
|
||||
|
||||
GitHubOAuthDto:
|
||||
type: object
|
||||
required:
|
||||
- github_id
|
||||
- username
|
||||
- nickname
|
||||
properties:
|
||||
github_id:
|
||||
type: string
|
||||
description: GitHub用户ID
|
||||
minLength: 1
|
||||
maxLength: 100
|
||||
example: "12345678"
|
||||
username:
|
||||
type: string
|
||||
description: GitHub用户名
|
||||
minLength: 1
|
||||
maxLength: 50
|
||||
example: octocat
|
||||
nickname:
|
||||
type: string
|
||||
description: GitHub显示名称
|
||||
minLength: 1
|
||||
maxLength: 50
|
||||
example: The Octocat
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
description: GitHub邮箱地址（可选）
|
||||
example: octocat@github.com
|
||||
avatar_url:
|
||||
type: string
|
||||
description: GitHub头像URL（可选）
|
||||
example: https://github.com/images/error/octocat_happy.gif
|
||||
|
||||
ForgotPasswordDto:
|
||||
type: object
|
||||
required:
|
||||
- identifier
|
||||
properties:
|
||||
identifier:
|
||||
type: string
|
||||
description: 邮箱或手机号
|
||||
minLength: 1
|
||||
maxLength: 100
|
||||
example: test@example.com
|
||||
|
||||
ResetPasswordDto:
|
||||
type: object
|
||||
required:
|
||||
- identifier
|
||||
- verification_code
|
||||
- new_password
|
||||
properties:
|
||||
identifier:
|
||||
type: string
|
||||
description: 邮箱或手机号
|
||||
minLength: 1
|
||||
maxLength: 100
|
||||
example: test@example.com
|
||||
verification_code:
|
||||
type: string
|
||||
description: 6位数字验证码
|
||||
pattern: '^\d{6}$'
|
||||
example: "123456"
|
||||
new_password:
|
||||
type: string
|
||||
description: 新密码，必须包含字母和数字，长度8-128字符
|
||||
minLength: 8
|
||||
maxLength: 128
|
||||
pattern: '^(?=.*[a-zA-Z])(?=.*\d)'
|
||||
example: newpassword123
|
||||
|
||||
ChangePasswordDto:
|
||||
type: object
|
||||
required:
|
||||
- user_id
|
||||
- old_password
|
||||
- new_password
|
||||
properties:
|
||||
user_id:
|
||||
type: string
|
||||
description: 用户ID（实际应用中应从JWT令牌中获取）
|
||||
example: "1"
|
||||
old_password:
|
||||
type: string
|
||||
description: 当前密码
|
||||
minLength: 1
|
||||
maxLength: 128
|
||||
example: oldpassword123
|
||||
new_password:
|
||||
type: string
|
||||
description: 新密码，必须包含字母和数字，长度8-128字符
|
||||
minLength: 8
|
||||
maxLength: 128
|
||||
pattern: '^(?=.*[a-zA-Z])(?=.*\d)'
|
||||
example: newpassword123
|
||||
|
||||
UserInfo:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: 用户ID
|
||||
example: "1"
|
||||
username:
|
||||
type: string
|
||||
description: 用户名
|
||||
example: testuser
|
||||
nickname:
|
||||
type: string
|
||||
description: 用户昵称
|
||||
example: 测试用户
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
description: 邮箱地址
|
||||
example: test@example.com
|
||||
phone:
|
||||
type: string
|
||||
description: 手机号码
|
||||
example: "+8613800138000"
|
||||
avatar_url:
|
||||
type: string
|
||||
description: 头像URL
|
||||
example: https://example.com/avatar.jpg
|
||||
role:
|
||||
type: integer
|
||||
description: 用户角色
|
||||
example: 1
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
description: 创建时间
|
||||
example: "2025-12-17T10:00:00.000Z"
|
||||
|
||||
LoginResponseData:
|
||||
type: object
|
||||
properties:
|
||||
user:
|
||||
$ref: '#/components/schemas/UserInfo'
|
||||
access_token:
|
||||
type: string
|
||||
description: 访问令牌
|
||||
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
refresh_token:
|
||||
type: string
|
||||
description: 刷新令牌
|
||||
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
is_new_user:
|
||||
type: boolean
|
||||
description: 是否为新用户
|
||||
example: false
|
||||
message:
|
||||
type: string
|
||||
description: 响应消息
|
||||
example: 登录成功
|
||||
|
||||
LoginResponse:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
description: 请求是否成功
|
||||
example: true
|
||||
data:
|
||||
$ref: '#/components/schemas/LoginResponseData'
|
||||
message:
|
||||
type: string
|
||||
description: 响应消息
|
||||
example: 登录成功
|
||||
|
||||
RegisterResponse:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
description: 请求是否成功
|
||||
example: true
|
||||
data:
|
||||
$ref: '#/components/schemas/LoginResponseData'
|
||||
message:
|
||||
type: string
|
||||
description: 响应消息
|
||||
example: 注册成功
|
||||
|
||||
GitHubOAuthResponse:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
description: 请求是否成功
|
||||
example: true
|
||||
data:
|
||||
$ref: '#/components/schemas/LoginResponseData'
|
||||
message:
|
||||
type: string
|
||||
description: 响应消息
|
||||
example: GitHub登录成功
|
||||
|
||||
ForgotPasswordResponseData:
|
||||
type: object
|
||||
properties:
|
||||
verification_code:
|
||||
type: string
|
||||
description: 验证码（仅用于演示，实际应用中不应返回）
|
||||
example: "123456"
|
||||
|
||||
ForgotPasswordResponse:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
description: 请求是否成功
|
||||
example: true
|
||||
data:
|
||||
$ref: '#/components/schemas/ForgotPasswordResponseData'
|
||||
message:
|
||||
type: string
|
||||
description: 响应消息
|
||||
example: 验证码已发送，请查收
|
||||
|
||||
CommonResponse:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
description: 请求是否成功
|
||||
example: true
|
||||
message:
|
||||
type: string
|
||||
description: 响应消息
|
||||
example: 操作成功
|
||||
|
||||
ErrorResponse:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
description: 请求是否成功
|
||||
example: false
|
||||
message:
|
||||
type: string
|
||||
description: 错误消息
|
||||
example: 操作失败
|
||||
error_code:
|
||||
type: string
|
||||
description: 错误代码
|
||||
example: OPERATION_FAILED
|
||||
Reference in New Issue
Block a user