{ "swagger": "2.0", "info": { "title": "聚玩打手服务", "description": "聚玩用户服务处理打手信息管理、服务发布及订单相关接口。ID 字段（int64）以 string 传输", "version": "1.0" }, "schemes": [ "http", "https" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/api/v1/players": { "get": { "summary": "获取打手列表", "operationId": "ListPlayers", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/PlayerListResp" } } }, "parameters": [ { "name": "offset", "in": "query", "required": true, "type": "integer", "format": "int64", "default": "0" }, { "name": "limit", "in": "query", "required": true, "type": "integer", "format": "int64", "default": "20" }, { "name": "gameId", "in": "query", "required": false, "type": "integer", "format": "int64" }, { "name": "gender", "in": "query", "required": false, "type": "integer", "format": "int64" } ], "tags": [ "player" ], "consumes": [ "multipart/form-data" ] } }, "/api/v1/players/me": { "get": { "summary": "获取当前用户的打手资料", "operationId": "GetMyPlayer", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/PlayerProfile" } } }, "tags": [ "player" ] }, "post": { "summary": "初始化当前用户的打手资料", "operationId": "InitPlayer", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/PlayerProfile" } } }, "parameters": [ { "name": "body", "description": " 空响应", "in": "body", "required": true, "schema": { "$ref": "#/definitions/EmptyResp" } } ], "tags": [ "player" ] } }, "/api/v1/players/me/status": { "put": { "summary": "更新接单状态", "operationId": "UpdatePlayerStatus", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/EmptyResp" } } }, "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/UpdatePlayerStatusReq" } } ], "tags": [ "player" ] } }, "/api/v1/players/{id}": { "get": { "summary": "获取打手详情", "operationId": "GetPlayer", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/PlayerProfile" } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "type": "string" } ], "tags": [ "player" ] } }, "/api/v1/players/{id}/services": { "get": { "summary": "获取指定打手的服务列表", "operationId": "ListPlayerServices", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/PlayerServiceListResp" } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "type": "string" }, { "name": "offset", "in": "query", "required": true, "type": "integer", "format": "int64", "default": "0" }, { "name": "limit", "in": "query", "required": true, "type": "integer", "format": "int64", "default": "20" } ], "tags": [ "player" ] } }, "/api/v1/services": { "get": { "summary": "获取所有服务列表", "operationId": "ListServices", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/PlayerServiceListResp" } } }, "parameters": [ { "name": "offset", "in": "query", "required": true, "type": "integer", "format": "int64", "default": "0" }, { "name": "limit", "in": "query", "required": true, "type": "integer", "format": "int64", "default": "20" } ], "tags": [ "player" ], "consumes": [ "multipart/form-data" ] }, "post": { "summary": "创建服务", "operationId": "CreateService", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/PlayerService" } } }, "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/CreateServiceReq" } } ], "tags": [ "player" ] } }, "/api/v1/services/{id}": { "get": { "summary": "获取服务详情", "operationId": "GetService", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/PlayerService" } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "type": "string" } ], "tags": [ "player" ] }, "delete": { "summary": "删除服务", "operationId": "DeleteService", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/EmptyResp" } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/DeleteServiceReq" } } ], "tags": [ "player" ] }, "put": { "summary": "更新服务", "operationId": "UpdateService", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/PlayerService" } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/UpdateServiceReq" } } ], "tags": [ "player" ] } } }, "definitions": { "CreateServiceReq": { "type": "object", "properties": { "gameId": { "type": "integer", "format": "int64" }, "title": { "type": "string" }, "description": { "type": "string" }, "price": { "type": "number", "format": "double" }, "unit": { "type": "string" }, "rankRange": { "type": "string" }, "availability": { "type": "array", "items": { "type": "string" } } }, "title": "CreateServiceReq", "required": [ "price", "unit" ] }, "DeleteServiceReq": { "type": "object", "title": "DeleteServiceReq" }, "EmptyResp": { "type": "object", "title": "EmptyResp" }, "GetPlayerReq": { "type": "object", "title": "GetPlayerReq" }, "GetServiceReq": { "type": "object", "title": "GetServiceReq" }, "ListPlayerServicesReq": { "type": "object", "properties": { "offset": { "type": "integer", "format": "int64", "default": "0" }, "limit": { "type": "integer", "format": "int64", "default": "20" } }, "title": "ListPlayerServicesReq" }, "PageMeta": { "type": "object", "properties": { "total": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "limit": { "type": "integer", "format": "int64" } }, "title": "PageMeta", "required": [ "total", "offset", "limit" ] }, "PageReq": { "type": "object", "properties": { "offset": { "type": "integer", "format": "int64", "default": "0" }, "limit": { "type": "integer", "format": "int64", "default": "20" } }, "title": "PageReq", "required": [ "offset", "limit" ] }, "PlayerListReq": { "type": "object", "properties": { "offset": { "type": "integer", "format": "int64", "default": "0" }, "limit": { "type": "integer", "format": "int64", "default": "20" }, "gameId": { "type": "integer", "format": "int64" }, "gender": { "type": "integer", "format": "int64" } }, "title": "PlayerListReq" }, "PlayerListResp": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/PlayerProfile" } }, "meta": { "$ref": "#/definitions/PageMeta" } }, "title": "PlayerListResp", "required": [ "items", "meta" ] }, "PlayerProfile": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "user": { "$ref": "#/definitions/UserProfile" }, "rating": { "type": "number", "format": "double" }, "totalOrders": { "type": "integer", "format": "int64" }, "completionRate": { "type": "number", "format": "double" }, "status": { "type": "string" }, "games": { "type": "array", "items": { "type": "string" } }, "services": { "type": "array", "items": { "$ref": "#/definitions/PlayerService" } }, "shopId": { "type": "string" }, "shopName": { "type": "string" }, "gender": { "type": "boolean", "format": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } } }, "title": "PlayerProfile", "required": [ "id", "user", "rating", "totalOrders", "completionRate", "status", "games", "services", "gender", "tags" ] }, "PlayerService": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "playerId": { "type": "integer", "format": "int64" }, "gameId": { "type": "integer", "format": "int64" }, "gameName": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "price": { "type": "number", "format": "double" }, "unit": { "type": "string" }, "rankRange": { "type": "string" }, "availability": { "type": "array", "items": { "type": "string" } } }, "title": "PlayerService", "required": [ "playerId", "gameId", "gameName", "title", "description", "price", "unit", "availability" ] }, "PlayerServiceListResp": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/PlayerService" } }, "meta": { "$ref": "#/definitions/PageMeta" } }, "title": "PlayerServiceListResp", "required": [ "items", "meta" ] }, "SimpleUser": { "type": "object", "properties": { "id": { "type": "string" }, "nickname": { "type": "string" }, "avatar": { "type": "string" } }, "title": "SimpleUser", "required": [ "id", "nickname", "avatar" ] }, "UpdatePlayerStatusReq": { "type": "object", "properties": { "status": { "type": "string" } }, "title": "UpdatePlayerStatusReq", "required": [ "status" ] }, "UpdateServiceReq": { "type": "object", "properties": { "gameId": { "type": "integer", "format": "int64" }, "title": { "type": "string" }, "description": { "type": "string" }, "price": { "type": "number", "format": "double" }, "unit": { "type": "string" }, "rankRange": { "type": "string" }, "availability": { "type": "array", "items": { "type": "string" } } }, "title": "UpdateServiceReq", "required": [ "availability" ] }, "UserProfile": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "type": "string" }, "nickname": { "type": "string" }, "avatar": { "type": "string" }, "role": { "type": "string", "description": " consumer, player, owner, admin" }, "verifiedRoles": { "type": "array", "items": { "type": "string" } }, "verificationStatus": { "type": "object" }, "phone": { "type": "string" }, "bio": { "type": "string" }, "createdAt": { "type": "string" } }, "title": "UserProfile", "required": [ "id", "username", "nickname", "avatar", "role", "verifiedRoles", "verificationStatus", "createdAt" ] } }, "securityDefinitions": { "apiKey": { "type": "apiKey", "description": "Enter JWT Bearer token **_only_**", "name": "Authorization", "in": "header" } } }