datawhale/whale-town-end
3
4
Fork 2
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs：创建完整的API接口文档

Browse Source 
- 创建详细的API接口说明文档
- 提供OpenAPI 3.0规范文件
- 创建Postman测试集合
- 添加API文档使用指南
This commit is contained in:
moyin
2025-12-17 15:16:27 +08:00
parent d28100e103
commit 1e47c4db60
4 changed files with 1468 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

347
docs/api/postman-collection.json Normal file
View File

@@ -0,0 +1,347 @@
{
"info": {
"name": "Pixel Game Server - Auth API",
"description": "像素游戏服务器用户认证API接口集合",
"version": "1.0.0",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"variable": [
{
"key": "baseUrl",
"value": "http://localhost:3000",
"type": "string"
}
],
"item": [
{
"name": "用户登录",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"identifier\": \"testuser\",\n \"password\": \"password123\"\n}"
},
"url": {
"raw": "{{baseUrl}}/auth/login",
"host": ["{{baseUrl}}"],
"path": ["auth", "login"]
},
"description": "用户登录接口，支持用户名、邮箱或手机号登录"
},
"response": [
{
"name": "登录成功",
"originalRequest": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"identifier\": \"testuser\",\n \"password\": \"password123\"\n}"
},
"url": {
"raw": "{{baseUrl}}/auth/login",
"host": ["{{baseUrl}}"],
"path": ["auth", "login"]
}
},
"status": "OK",
"code": 200,
"_postman_previewlanguage": "json",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": "{\n \"success\": true,\n \"data\": {\n \"user\": {\n \"id\": \"1\",\n \"username\": \"testuser\",\n \"nickname\": \"测试用户\",\n \"email\": \"test@example.com\",\n \"phone\": \"+8613800138000\",\n \"avatar_url\": \"https://example.com/avatar.jpg\",\n \"role\": 1,\n \"created_at\": \"2025-12-17T10:00:00.000Z\"\n },\n \"access_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"refresh_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"is_new_user\": false,\n \"message\": \"登录成功\"\n },\n \"message\": \"登录成功\"\n}"
}
]
},
{
"name": "用户注册",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"username\": \"newuser\",\n \"password\": \"password123\",\n \"nickname\": \"新用户\",\n \"email\": \"newuser@example.com\",\n \"phone\": \"+8613800138001\"\n}"
},
"url": {
"raw": "{{baseUrl}}/auth/register",
"host": ["{{baseUrl}}"],
"path": ["auth", "register"]
},
"description": "用户注册接口，创建新用户账户"
},
"response": [
{
"name": "注册成功",
"originalRequest": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"username\": \"newuser\",\n \"password\": \"password123\",\n \"nickname\": \"新用户\",\n \"email\": \"newuser@example.com\",\n \"phone\": \"+8613800138001\"\n}"
},
"url": {
"raw": "{{baseUrl}}/auth/register",
"host": ["{{baseUrl}}"],
"path": ["auth", "register"]
}
},
"status": "Created",
"code": 201,
"_postman_previewlanguage": "json",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": "{\n \"success\": true,\n \"data\": {\n \"user\": {\n \"id\": \"2\",\n \"username\": \"newuser\",\n \"nickname\": \"新用户\",\n \"email\": \"newuser@example.com\",\n \"phone\": \"+8613800138001\",\n \"avatar_url\": null,\n \"role\": 1,\n \"created_at\": \"2025-12-17T10:00:00.000Z\"\n },\n \"access_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"is_new_user\": true,\n \"message\": \"注册成功\"\n },\n \"message\": \"注册成功\"\n}"
}
]
},
{
"name": "GitHub OAuth登录",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"github_id\": \"12345678\",\n \"username\": \"octocat\",\n \"nickname\": \"The Octocat\",\n \"email\": \"octocat@github.com\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\"\n}"
},
"url": {
"raw": "{{baseUrl}}/auth/github",
"host": ["{{baseUrl}}"],
"path": ["auth", "github"]
},
"description": "GitHub OAuth登录接口，使用GitHub账户登录或注册"
},
"response": [
{
"name": "GitHub登录成功",
"originalRequest": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"github_id\": \"12345678\",\n \"username\": \"octocat\",\n \"nickname\": \"The Octocat\",\n \"email\": \"octocat@github.com\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\"\n}"
},
"url": {
"raw": "{{baseUrl}}/auth/github",
"host": ["{{baseUrl}}"],
"path": ["auth", "github"]
}
},
"status": "OK",
"code": 200,
"_postman_previewlanguage": "json",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": "{\n \"success\": true,\n \"data\": {\n \"user\": {\n \"id\": \"3\",\n \"username\": \"octocat\",\n \"nickname\": \"The Octocat\",\n \"email\": \"octocat@github.com\",\n \"phone\": null,\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"role\": 1,\n \"created_at\": \"2025-12-17T10:00:00.000Z\"\n },\n \"access_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"is_new_user\": true,\n \"message\": \"GitHub账户绑定成功\"\n },\n \"message\": \"GitHub账户绑定成功\"\n}"
}
]
},
{
"name": "发送密码重置验证码",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"identifier\": \"test@example.com\"\n}"
},
"url": {
"raw": "{{baseUrl}}/auth/forgot-password",
"host": ["{{baseUrl}}"],
"path": ["auth", "forgot-password"]
},
"description": "发送密码重置验证码到用户邮箱或手机"
},
"response": [
{
"name": "验证码发送成功",
"originalRequest": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"identifier\": \"test@example.com\"\n}"
},
"url": {
"raw": "{{baseUrl}}/auth/forgot-password",
"host": ["{{baseUrl}}"],
"path": ["auth", "forgot-password"]
}
},
"status": "OK",
"code": 200,
"_postman_previewlanguage": "json",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": "{\n \"success\": true,\n \"data\": {\n \"verification_code\": \"123456\"\n },\n \"message\": \"验证码已发送，请查收\"\n}"
}
]
},
{
"name": "重置密码",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"identifier\": \"test@example.com\",\n \"verification_code\": \"123456\",\n \"new_password\": \"newpassword123\"\n}"
},
"url": {
"raw": "{{baseUrl}}/auth/reset-password",
"host": ["{{baseUrl}}"],
"path": ["auth", "reset-password"]
},
"description": "使用验证码重置用户密码"
},
"response": [
{
"name": "密码重置成功",
"originalRequest": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"identifier\": \"test@example.com\",\n \"verification_code\": \"123456\",\n \"new_password\": \"newpassword123\"\n}"
},
"url": {
"raw": "{{baseUrl}}/auth/reset-password",
"host": ["{{baseUrl}}"],
"path": ["auth", "reset-password"]
}
},
"status": "OK",
"code": 200,
"_postman_previewlanguage": "json",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": "{\n \"success\": true,\n \"message\": \"密码重置成功\"\n}"
}
]
},
{
"name": "修改密码",
"request": {
"method": "PUT",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"user_id\": \"1\",\n \"old_password\": \"oldpassword123\",\n \"new_password\": \"newpassword123\"\n}"
},
"url": {
"raw": "{{baseUrl}}/auth/change-password",
"host": ["{{baseUrl}}"],
"path": ["auth", "change-password"]
},
"description": "用户修改自己的密码（需要提供旧密码）"
},
"response": [
{
"name": "密码修改成功",
"originalRequest": {
"method": "PUT",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"user_id\": \"1\",\n \"old_password\": \"oldpassword123\",\n \"new_password\": \"newpassword123\"\n}"
},
"url": {
"raw": "{{baseUrl}}/auth/change-password",
"host": ["{{baseUrl}}"],
"path": ["auth", "change-password"]
}
},
"status": "OK",
"code": 200,
"_postman_previewlanguage": "json",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": "{\n \"success\": true,\n \"message\": \"密码修改成功\"\n}"
}
]
}
]
}