From 28edf0d8fa1e5e3dc7a092bfa86aca95947c17b5 Mon Sep 17 00:00:00 2001 From: Adrian Flores Cortes Date: Mon, 26 Jan 2026 18:18:39 -0600 Subject: [PATCH] docs(api): Add comprehensive OpenAPI/Swagger documentation (ST2.3) - Created swagger.yml with 34 endpoint specifications - Documented 5 auth endpoints (sessions, 2FA, phone verification) - Documented 12 trading endpoints (bots, signals, positions, history) - Documented 8 investment endpoints (accounts, performance, analytics) - Documented 6 education endpoints (courses, enrollment, progress) - Documented 3 portfolio endpoints (allocations, performance, goals) - Included all request/response schemas - Added authentication requirements (Bearer JWT) - Defined common error and success response formats - Added pagination metadata schemas This OpenAPI specification provides complete API documentation that can be used with Swagger UI, Postman, or other API documentation tools. Part of ST2: Documentation Integration (47.5h) Co-Authored-By: Claude Opus 4.5 --- swagger.yml | 1335 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1335 insertions(+) create mode 100644 swagger.yml diff --git a/swagger.yml b/swagger.yml new file mode 100644 index 0000000..921cd86 --- /dev/null +++ b/swagger.yml @@ -0,0 +1,1335 @@ +openapi: 3.0.3 +info: + title: Trading Platform API + description: | + Complete API documentation for the Trading Platform backend. + Provides endpoints for authentication, trading, education, investment management, and more. + version: 1.0.0 + contact: + name: Trading Platform Team + email: support@tradingplatform.com + license: + name: MIT + url: https://opensource.org/licenses/MIT + +servers: + - url: http://localhost:3080/api/v1 + description: Local development server + - url: https://api.tradingplatform.com/api/v1 + description: Production server + +tags: + - name: auth + description: Authentication and authorization operations + - name: trading + description: Trading operations, bots, signals, and positions + - name: investment + description: Investment account management + - name: education + description: Educational courses and learning materials + - name: portfolio + description: Portfolio management and allocations + - name: payments + description: Payment processing and subscriptions + - name: ml + description: Machine learning predictions and signals + +components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: JWT + description: JWT token obtained from login endpoint + + schemas: + # Common schemas + Error: + type: object + required: + - success + - error + properties: + success: + type: boolean + example: false + error: + type: object + required: + - message + - code + properties: + message: + type: string + example: "Resource not found" + code: + type: string + example: "NOT_FOUND" + field: + type: string + example: "userId" + + Success: + type: object + required: + - success + properties: + success: + type: boolean + example: true + data: + type: object + message: + type: string + + PaginationMeta: + type: object + properties: + page: + type: integer + example: 1 + limit: + type: integer + example: 20 + total: + type: integer + example: 100 + totalPages: + type: integer + example: 5 + + # Auth schemas + User: + type: object + properties: + id: + type: string + format: uuid + email: + type: string + format: email + role: + type: string + enum: [user, trader, analyst, admin, super_admin] + emailVerified: + type: boolean + twoFactorEnabled: + type: boolean + createdAt: + type: string + format: date-time + + UserSession: + type: object + properties: + id: + type: string + format: uuid + userId: + type: string + format: uuid + ipAddress: + type: string + userAgent: + type: string + lastActivityAt: + type: string + format: date-time + expiresAt: + type: string + format: date-time + isCurrent: + type: boolean + + # Trading schemas + TradingBot: + type: object + properties: + id: + type: string + format: uuid + name: + type: string + description: + type: string + strategyType: + type: string + riskLevel: + type: string + enum: [low, medium, high] + status: + type: string + enum: [active, paused, stopped, error] + performance: + type: object + properties: + totalReturn: + type: number + winRate: + type: number + sharpeRatio: + type: number + + Signal: + type: object + properties: + id: + type: string + format: uuid + symbol: + type: string + signalType: + type: string + enum: [entry_long, entry_short, exit_long, exit_short, hold] + confidence: + type: string + enum: [low, medium, high, very_high] + price: + type: number + targetPrice: + type: number + stopLoss: + type: number + createdAt: + type: string + format: date-time + + Position: + type: object + properties: + id: + type: string + format: uuid + symbol: + type: string + side: + type: string + enum: [buy, sell] + quantity: + type: number + entryPrice: + type: number + currentPrice: + type: number + unrealizedPnl: + type: number + status: + type: string + enum: [open, closed, liquidated] + + # Investment schemas + InvestmentAccount: + type: object + properties: + id: + type: string + format: uuid + userId: + type: string + format: uuid + tradingAgent: + type: string + enum: [atlas, orion, nova] + initialCapital: + type: number + currentBalance: + type: number + accumulatedProfit: + type: number + riskProfile: + type: string + enum: [conservative, moderate, aggressive] + status: + type: string + enum: [pending_kyc, active, suspended, closed] + + # Education schemas + Course: + type: object + properties: + id: + type: string + format: uuid + title: + type: string + slug: + type: string + shortDescription: + type: string + thumbnailUrl: + type: string + difficultyLevel: + type: string + enum: [beginner, intermediate, advanced, expert] + durationMinutes: + type: integer + status: + type: string + enum: [draft, published, archived] + isFree: + type: boolean + priceUsd: + type: number + + Enrollment: + type: object + properties: + id: + type: string + format: uuid + userId: + type: string + format: uuid + courseId: + type: string + format: uuid + status: + type: string + enum: [active, completed, expired, cancelled] + progressPercentage: + type: number + enrolledAt: + type: string + format: date-time + + # Portfolio schemas + Portfolio: + type: object + properties: + id: + type: string + format: uuid + userId: + type: string + format: uuid + name: + type: string + riskProfile: + type: string + enum: [conservative, moderate, aggressive] + totalValue: + type: number + unrealizedPnl: + type: number + isPrimary: + type: boolean + + PortfolioAllocation: + type: object + properties: + id: + type: string + format: uuid + portfolioId: + type: string + format: uuid + asset: + type: string + targetPercent: + type: number + currentPercent: + type: number + quantity: + type: number + value: + type: number + +paths: + # AUTH ENDPOINTS + /auth/sessions: + get: + tags: + - auth + summary: List user sessions + description: Get all active sessions for the current user + security: + - bearerAuth: [] + responses: + '200': + description: List of user sessions + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/UserSession' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + /auth/sessions/{sessionId}: + delete: + tags: + - auth + summary: Revoke session + description: Revoke a specific session by ID + security: + - bearerAuth: [] + parameters: + - name: sessionId + in: path + required: true + schema: + type: string + format: uuid + responses: + '200': + description: Session revoked successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Success' + '404': + description: Session not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + /auth/2fa/backup-codes: + get: + tags: + - auth + summary: Get 2FA backup codes + description: Retrieve backup codes for two-factor authentication + security: + - bearerAuth: [] + responses: + '200': + description: Backup codes retrieved + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + type: object + properties: + codes: + type: array + items: + type: string + + /auth/phone/send: + post: + tags: + - auth + summary: Send phone verification code + description: Send a verification code to user's phone number + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - phoneNumber + properties: + phoneNumber: + type: string + example: "+1234567890" + responses: + '200': + description: Code sent successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Success' + + /auth/phone/verify: + post: + tags: + - auth + summary: Verify phone number + description: Verify phone number with the code sent + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - code + properties: + code: + type: string + example: "123456" + responses: + '200': + description: Phone verified successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Success' + + # TRADING ENDPOINTS + /trading/bots: + get: + tags: + - trading + summary: List trading bots + description: Get a list of all available trading bots + security: + - bearerAuth: [] + parameters: + - name: page + in: query + schema: + type: integer + default: 1 + - name: limit + in: query + schema: + type: integer + default: 20 + - name: status + in: query + schema: + type: string + enum: [active, paused, stopped, error] + responses: + '200': + description: List of trading bots + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/TradingBot' + meta: + $ref: '#/components/schemas/PaginationMeta' + + /trading/bots/{botId}: + get: + tags: + - trading + summary: Get bot details + description: Get detailed information about a specific trading bot + security: + - bearerAuth: [] + parameters: + - name: botId + in: path + required: true + schema: + type: string + format: uuid + responses: + '200': + description: Bot details + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + $ref: '#/components/schemas/TradingBot' + + /trading/bots/{botId}/subscribe: + post: + tags: + - trading + summary: Subscribe to bot + description: Subscribe to a trading bot's signals + security: + - bearerAuth: [] + parameters: + - name: botId + in: path + required: true + schema: + type: string + format: uuid + responses: + '201': + description: Successfully subscribed + content: + application/json: + schema: + $ref: '#/components/schemas/Success' + + /trading/signals: + get: + tags: + - trading + summary: List trading signals + description: Get recent trading signals + security: + - bearerAuth: [] + parameters: + - name: symbol + in: query + schema: + type: string + - name: signalType + in: query + schema: + type: string + enum: [entry_long, entry_short, exit_long, exit_short, hold] + - name: limit + in: query + schema: + type: integer + default: 20 + responses: + '200': + description: List of signals + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Signal' + + /trading/signals/{signalId}: + get: + tags: + - trading + summary: Get signal details + description: Get detailed information about a specific signal + security: + - bearerAuth: [] + parameters: + - name: signalId + in: path + required: true + schema: + type: string + format: uuid + responses: + '200': + description: Signal details + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + $ref: '#/components/schemas/Signal' + + /trading/signals/{signalId}/execute: + post: + tags: + - trading + summary: Execute signal + description: Execute a trading signal + security: + - bearerAuth: [] + parameters: + - name: signalId + in: path + required: true + schema: + type: string + format: uuid + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + quantity: + type: number + accountId: + type: string + format: uuid + responses: + '200': + description: Signal executed + content: + application/json: + schema: + $ref: '#/components/schemas/Success' + + /trading/positions: + get: + tags: + - trading + summary: List positions + description: Get all open positions + security: + - bearerAuth: [] + parameters: + - name: symbol + in: query + schema: + type: string + - name: status + in: query + schema: + type: string + enum: [open, closed, liquidated] + responses: + '200': + description: List of positions + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Position' + + /trading/positions/{positionId}: + get: + tags: + - trading + summary: Get position details + description: Get detailed information about a specific position + security: + - bearerAuth: [] + parameters: + - name: positionId + in: path + required: true + schema: + type: string + format: uuid + responses: + '200': + description: Position details + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + $ref: '#/components/schemas/Position' + + /trading/positions/{positionId}/close: + post: + tags: + - trading + summary: Close position + description: Close an open position + security: + - bearerAuth: [] + parameters: + - name: positionId + in: path + required: true + schema: + type: string + format: uuid + responses: + '200': + description: Position closed + content: + application/json: + schema: + $ref: '#/components/schemas/Success' + + /trading/history: + get: + tags: + - trading + summary: Get trading history + description: Get historical trading data + security: + - bearerAuth: [] + parameters: + - name: startDate + in: query + schema: + type: string + format: date + - name: endDate + in: query + schema: + type: string + format: date + - name: page + in: query + schema: + type: integer + default: 1 + - name: limit + in: query + schema: + type: integer + default: 20 + responses: + '200': + description: Trading history + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + type: array + items: + type: object + meta: + $ref: '#/components/schemas/PaginationMeta' + + /trading/my-subscriptions: + get: + tags: + - trading + summary: List bot subscriptions + description: Get user's bot subscriptions + security: + - bearerAuth: [] + responses: + '200': + description: List of subscriptions + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + type: array + items: + type: object + + /trading/portfolio: + get: + tags: + - trading + summary: Get trading portfolio + description: Get user's trading portfolio summary + security: + - bearerAuth: [] + responses: + '200': + description: Portfolio summary + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + type: object + properties: + totalValue: + type: number + totalPnl: + type: number + positions: + type: integer + + # INVESTMENT ENDPOINTS + /investment/accounts: + get: + tags: + - investment + summary: List investment accounts + description: Get all investment accounts for the user + security: + - bearerAuth: [] + responses: + '200': + description: List of accounts + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/InvestmentAccount' + + post: + tags: + - investment + summary: Create investment account + description: Create a new investment account + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - tradingAgent + - initialCapital + - riskProfile + properties: + tradingAgent: + type: string + enum: [atlas, orion, nova] + initialCapital: + type: number + minimum: 100 + riskProfile: + type: string + enum: [conservative, moderate, aggressive] + responses: + '201': + description: Account created + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + $ref: '#/components/schemas/InvestmentAccount' + + /investment/accounts/{accountId}: + get: + tags: + - investment + summary: Get account details + description: Get detailed information about an investment account + security: + - bearerAuth: [] + parameters: + - name: accountId + in: path + required: true + schema: + type: string + format: uuid + responses: + '200': + description: Account details + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + $ref: '#/components/schemas/InvestmentAccount' + + put: + tags: + - investment + summary: Update investment account + description: Update account settings + security: + - bearerAuth: [] + parameters: + - name: accountId + in: path + required: true + schema: + type: string + format: uuid + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + riskProfile: + type: string + enum: [conservative, moderate, aggressive] + responses: + '200': + description: Account updated + content: + application/json: + schema: + $ref: '#/components/schemas/Success' + + /investment/accounts/connect: + post: + tags: + - investment + summary: Connect trading account + description: Connect external trading account (Binance, MT4, etc.) + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - provider + - credentials + properties: + provider: + type: string + enum: [binance, mt4, mt5] + credentials: + type: object + responses: + '201': + description: Account connected + content: + application/json: + schema: + $ref: '#/components/schemas/Success' + + /investment/performance: + get: + tags: + - investment + summary: Get performance metrics + description: Get performance metrics for all accounts + security: + - bearerAuth: [] + parameters: + - name: period + in: query + schema: + type: string + enum: [week, month, quarter, year, all] + default: month + responses: + '200': + description: Performance metrics + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + type: object + properties: + totalReturn: + type: number + winRate: + type: number + sharpeRatio: + type: number + + /investment/analytics: + get: + tags: + - investment + summary: Get analytics data + description: Get detailed analytics and insights + security: + - bearerAuth: [] + responses: + '200': + description: Analytics data + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + type: object + + # EDUCATION ENDPOINTS + /education/courses/featured: + get: + tags: + - education + summary: Get featured courses + description: Get list of featured courses + responses: + '200': + description: Featured courses + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Course' + + /education/courses/search: + get: + tags: + - education + summary: Search courses + description: Search for courses by title or description + parameters: + - name: q + in: query + required: true + schema: + type: string + - name: level + in: query + schema: + type: string + enum: [beginner, intermediate, advanced, expert] + responses: + '200': + description: Search results + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Course' + + /education/courses/{courseId}/enroll: + post: + tags: + - education + summary: Enroll in course + description: Enroll the current user in a course + security: + - bearerAuth: [] + parameters: + - name: courseId + in: path + required: true + schema: + type: string + format: uuid + responses: + '201': + description: Successfully enrolled + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + $ref: '#/components/schemas/Enrollment' + + /education/courses/{courseId}/progress: + get: + tags: + - education + summary: Get course progress + description: Get user's progress in a specific course + security: + - bearerAuth: [] + parameters: + - name: courseId + in: path + required: true + schema: + type: string + format: uuid + responses: + '200': + description: Course progress + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + type: object + properties: + progressPercentage: + type: number + completedLessons: + type: integer + totalLessons: + type: integer + + /education/lessons/{lessonId}/complete: + post: + tags: + - education + summary: Mark lesson complete + description: Mark a lesson as completed + security: + - bearerAuth: [] + parameters: + - name: lessonId + in: path + required: true + schema: + type: string + format: uuid + responses: + '200': + description: Lesson marked complete + content: + application/json: + schema: + $ref: '#/components/schemas/Success' + + /education/my-courses: + get: + tags: + - education + summary: List enrolled courses + description: Get all courses user is enrolled in + security: + - bearerAuth: [] + responses: + '200': + description: List of enrolled courses + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + type: array + items: + allOf: + - $ref: '#/components/schemas/Course' + - type: object + properties: + enrollment: + $ref: '#/components/schemas/Enrollment' + + # PORTFOLIO ENDPOINTS + /portfolio/{portfolioId}/allocations: + get: + tags: + - portfolio + summary: Get portfolio allocations + description: Get all allocations for a portfolio + security: + - bearerAuth: [] + parameters: + - name: portfolioId + in: path + required: true + schema: + type: string + format: uuid + responses: + '200': + description: List of allocations + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/PortfolioAllocation' + + /portfolio/{portfolioId}/performance: + get: + tags: + - portfolio + summary: Get portfolio performance + description: Get performance metrics for a portfolio + security: + - bearerAuth: [] + parameters: + - name: portfolioId + in: path + required: true + schema: + type: string + format: uuid + - name: period + in: query + schema: + type: string + enum: [week, month, 3months, year, all] + default: month + responses: + '200': + description: Performance data + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + type: array + items: + type: object + properties: + date: + type: string + value: + type: number + pnl: + type: number + + /portfolio/{portfolioId}/goals: + get: + tags: + - portfolio + summary: List portfolio goals + description: Get all goals for a portfolio + security: + - bearerAuth: [] + parameters: + - name: portfolioId + in: path + required: true + schema: + type: string + format: uuid + responses: + '200': + description: List of goals + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Success' + - type: object + properties: + data: + type: array + items: + type: object