568 lines
19 KiB
JSON
568 lines
19 KiB
JSON
{
|
||
"swagger": "2.0",
|
||
"info": {
|
||
"description": "基于DDD和Clean Architecture的企业级后端API服务\n采用Gin框架构建，支持用户管理、JWT认证、事件驱动等功能",
|
||
"title": "TYAPI Server API",
|
||
"contact": {
|
||
"name": "API Support",
|
||
"url": "https://github.com/your-org/tyapi-server-gin",
|
||
"email": "support@example.com"
|
||
},
|
||
"license": {
|
||
"name": "Apache 2.0",
|
||
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
|
||
},
|
||
"version": "1.0"
|
||
},
|
||
"host": "localhost:8080",
|
||
"basePath": "/api/v1",
|
||
"paths": {
|
||
"/users/login-password": {
|
||
"post": {
|
||
"description": "使用手机号和密码进行用户登录，返回JWT令牌",
|
||
"consumes": [
|
||
"application/json"
|
||
],
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"用户认证"
|
||
],
|
||
"summary": "用户密码登录",
|
||
"parameters": [
|
||
{
|
||
"description": "密码登录请求",
|
||
"name": "request",
|
||
"in": "body",
|
||
"required": true,
|
||
"schema": {
|
||
"$ref": "#/definitions/dto.LoginWithPasswordRequest"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "登录成功",
|
||
"schema": {
|
||
"$ref": "#/definitions/dto.LoginResponse"
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "请求参数错误",
|
||
"schema": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "认证失败",
|
||
"schema": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "服务器内部错误",
|
||
"schema": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/users/login-sms": {
|
||
"post": {
|
||
"description": "使用手机号和短信验证码进行用户登录，返回JWT令牌",
|
||
"consumes": [
|
||
"application/json"
|
||
],
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"用户认证"
|
||
],
|
||
"summary": "用户短信验证码登录",
|
||
"parameters": [
|
||
{
|
||
"description": "短信登录请求",
|
||
"name": "request",
|
||
"in": "body",
|
||
"required": true,
|
||
"schema": {
|
||
"$ref": "#/definitions/dto.LoginWithSMSRequest"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "登录成功",
|
||
"schema": {
|
||
"$ref": "#/definitions/dto.LoginResponse"
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "请求参数错误或验证码无效",
|
||
"schema": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "认证失败",
|
||
"schema": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "服务器内部错误",
|
||
"schema": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/users/me": {
|
||
"get": {
|
||
"security": [
|
||
{
|
||
"Bearer": []
|
||
}
|
||
],
|
||
"description": "根据JWT令牌获取当前登录用户的详细信息",
|
||
"consumes": [
|
||
"application/json"
|
||
],
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"用户管理"
|
||
],
|
||
"summary": "获取当前用户信息",
|
||
"responses": {
|
||
"200": {
|
||
"description": "用户信息",
|
||
"schema": {
|
||
"$ref": "#/definitions/dto.UserResponse"
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "未认证",
|
||
"schema": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
},
|
||
"404": {
|
||
"description": "用户不存在",
|
||
"schema": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "服务器内部错误",
|
||
"schema": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/users/me/password": {
|
||
"put": {
|
||
"security": [
|
||
{
|
||
"Bearer": []
|
||
}
|
||
],
|
||
"description": "使用旧密码、新密码确认和验证码修改当前用户的密码",
|
||
"consumes": [
|
||
"application/json"
|
||
],
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"用户管理"
|
||
],
|
||
"summary": "修改密码",
|
||
"parameters": [
|
||
{
|
||
"description": "修改密码请求",
|
||
"name": "request",
|
||
"in": "body",
|
||
"required": true,
|
||
"schema": {
|
||
"$ref": "#/definitions/dto.ChangePasswordRequest"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "密码修改成功",
|
||
"schema": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "请求参数错误或验证码无效",
|
||
"schema": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "未认证",
|
||
"schema": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "服务器内部错误",
|
||
"schema": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/users/register": {
|
||
"post": {
|
||
"description": "使用手机号、密码和验证码进行用户注册，需要确认密码",
|
||
"consumes": [
|
||
"application/json"
|
||
],
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"用户认证"
|
||
],
|
||
"summary": "用户注册",
|
||
"parameters": [
|
||
{
|
||
"description": "用户注册请求",
|
||
"name": "request",
|
||
"in": "body",
|
||
"required": true,
|
||
"schema": {
|
||
"$ref": "#/definitions/dto.RegisterRequest"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"201": {
|
||
"description": "注册成功",
|
||
"schema": {
|
||
"$ref": "#/definitions/dto.UserResponse"
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "请求参数错误或验证码无效",
|
||
"schema": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
},
|
||
"409": {
|
||
"description": "手机号已存在",
|
||
"schema": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "服务器内部错误",
|
||
"schema": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/users/send-code": {
|
||
"post": {
|
||
"description": "向指定手机号发送验证码，支持注册、登录、修改密码等场景",
|
||
"consumes": [
|
||
"application/json"
|
||
],
|
||
"produces": [
|
||
"application/json"
|
||
],
|
||
"tags": [
|
||
"用户认证"
|
||
],
|
||
"summary": "发送短信验证码",
|
||
"parameters": [
|
||
{
|
||
"description": "发送验证码请求",
|
||
"name": "request",
|
||
"in": "body",
|
||
"required": true,
|
||
"schema": {
|
||
"$ref": "#/definitions/dto.SendCodeRequest"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "验证码发送成功",
|
||
"schema": {
|
||
"$ref": "#/definitions/dto.SendCodeResponse"
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "请求参数错误",
|
||
"schema": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
},
|
||
"429": {
|
||
"description": "请求频率限制",
|
||
"schema": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "服务器内部错误",
|
||
"schema": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"definitions": {
|
||
"dto.ChangePasswordRequest": {
|
||
"type": "object",
|
||
"required": [
|
||
"code",
|
||
"confirm_new_password",
|
||
"new_password",
|
||
"old_password"
|
||
],
|
||
"properties": {
|
||
"code": {
|
||
"type": "string",
|
||
"example": "123456"
|
||
},
|
||
"confirm_new_password": {
|
||
"type": "string",
|
||
"example": "newpassword123"
|
||
},
|
||
"new_password": {
|
||
"type": "string",
|
||
"maxLength": 128,
|
||
"minLength": 6,
|
||
"example": "newpassword123"
|
||
},
|
||
"old_password": {
|
||
"type": "string",
|
||
"example": "oldpassword123"
|
||
}
|
||
}
|
||
},
|
||
"dto.LoginResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"access_token": {
|
||
"type": "string",
|
||
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||
},
|
||
"expires_in": {
|
||
"type": "integer",
|
||
"example": 86400
|
||
},
|
||
"login_method": {
|
||
"description": "password 或 sms",
|
||
"type": "string",
|
||
"example": "password"
|
||
},
|
||
"token_type": {
|
||
"type": "string",
|
||
"example": "Bearer"
|
||
},
|
||
"user": {
|
||
"$ref": "#/definitions/dto.UserResponse"
|
||
}
|
||
}
|
||
},
|
||
"dto.LoginWithPasswordRequest": {
|
||
"type": "object",
|
||
"required": [
|
||
"password",
|
||
"phone"
|
||
],
|
||
"properties": {
|
||
"password": {
|
||
"type": "string",
|
||
"example": "password123"
|
||
},
|
||
"phone": {
|
||
"type": "string",
|
||
"example": "13800138000"
|
||
}
|
||
}
|
||
},
|
||
"dto.LoginWithSMSRequest": {
|
||
"type": "object",
|
||
"required": [
|
||
"code",
|
||
"phone"
|
||
],
|
||
"properties": {
|
||
"code": {
|
||
"type": "string",
|
||
"example": "123456"
|
||
},
|
||
"phone": {
|
||
"type": "string",
|
||
"example": "13800138000"
|
||
}
|
||
}
|
||
},
|
||
"dto.RegisterRequest": {
|
||
"type": "object",
|
||
"required": [
|
||
"code",
|
||
"confirm_password",
|
||
"password",
|
||
"phone"
|
||
],
|
||
"properties": {
|
||
"code": {
|
||
"type": "string",
|
||
"example": "123456"
|
||
},
|
||
"confirm_password": {
|
||
"type": "string",
|
||
"example": "password123"
|
||
},
|
||
"password": {
|
||
"type": "string",
|
||
"maxLength": 128,
|
||
"minLength": 6,
|
||
"example": "password123"
|
||
},
|
||
"phone": {
|
||
"type": "string",
|
||
"example": "13800138000"
|
||
}
|
||
}
|
||
},
|
||
"dto.SendCodeRequest": {
|
||
"type": "object",
|
||
"required": [
|
||
"phone",
|
||
"scene"
|
||
],
|
||
"properties": {
|
||
"phone": {
|
||
"type": "string",
|
||
"example": "13800138000"
|
||
},
|
||
"scene": {
|
||
"enum": [
|
||
"register",
|
||
"login",
|
||
"change_password",
|
||
"reset_password",
|
||
"bind",
|
||
"unbind"
|
||
],
|
||
"allOf": [
|
||
{
|
||
"$ref": "#/definitions/entities.SMSScene"
|
||
}
|
||
],
|
||
"example": "register"
|
||
}
|
||
}
|
||
},
|
||
"dto.SendCodeResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"expires_at": {
|
||
"type": "string",
|
||
"example": "2024-01-01T00:05:00Z"
|
||
},
|
||
"message": {
|
||
"type": "string",
|
||
"example": "验证码发送成功"
|
||
}
|
||
}
|
||
},
|
||
"dto.UserResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"created_at": {
|
||
"type": "string",
|
||
"example": "2024-01-01T00:00:00Z"
|
||
},
|
||
"id": {
|
||
"type": "string",
|
||
"example": "123e4567-e89b-12d3-a456-426614174000"
|
||
},
|
||
"phone": {
|
||
"type": "string",
|
||
"example": "13800138000"
|
||
},
|
||
"updated_at": {
|
||
"type": "string",
|
||
"example": "2024-01-01T00:00:00Z"
|
||
}
|
||
}
|
||
},
|
||
"entities.SMSScene": {
|
||
"type": "string",
|
||
"enum": [
|
||
"register",
|
||
"login",
|
||
"change_password",
|
||
"reset_password",
|
||
"bind",
|
||
"unbind"
|
||
],
|
||
"x-enum-comments": {
|
||
"SMSSceneBind": "绑定手机号",
|
||
"SMSSceneChangePassword": "修改密码",
|
||
"SMSSceneLogin": "登录",
|
||
"SMSSceneRegister": "注册",
|
||
"SMSSceneResetPassword": "重置密码",
|
||
"SMSSceneUnbind": "解绑手机号"
|
||
},
|
||
"x-enum-varnames": [
|
||
"SMSSceneRegister",
|
||
"SMSSceneLogin",
|
||
"SMSSceneChangePassword",
|
||
"SMSSceneResetPassword",
|
||
"SMSSceneBind",
|
||
"SMSSceneUnbind"
|
||
]
|
||
}
|
||
},
|
||
"securityDefinitions": {
|
||
"Bearer": {
|
||
"description": "Type \"Bearer\" followed by a space and JWT token.",
|
||
"type": "apiKey",
|
||
"name": "Authorization",
|
||
"in": "header"
|
||
}
|
||
}
|
||
} |