Add Interactive API Documentation with Swagger UI and OpenAPI 3.0 Spec

[llinsss]

Problem

API documentation is incomplete and scattered. Developers integrating with Tagged need comprehensive, interactive API documentation with examples and testing capabilities.

Proposed Solution

Implement Swagger/OpenAPI 3.0 specification with interactive Swagger UI for all API endpoints.

Technical Implementation

New Files:

• backend/docs/openapi.yaml - OpenAPI 3.0 specification
• backend/docs/swagger-config.js - Swagger configuration
• backend/middleware/swaggerAuth.js - Swagger authentication
• backend/routes/docs.js - Documentation routes
• backend/scripts/generate-openapi.js - Auto-generate spec from routes
• backend/tests/swagger.test.js - Test suite

Modify:

• backend/app.js - Add Swagger UI middleware
• backend/package.json - Add swagger-ui-express, swagger-jsdoc
• backend/.env.example - Add SWAGGER_ENABLED flag
• backend/README.md - Add API documentation section

OpenAPI Structure

openapi: 3.0.0
info:
  title: Tagged PayCrypt API
  version: 2.0.0
  description: Seamless crypto payments for Africa
servers:
  - url: https://api.taggedpay.xyz/v1
    description: Production
  - url: http://localhost:3000/api
    description: Development

paths:
  /auth/register:
    post:
      summary: Register new user
      tags: [Authentication]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
      responses:
        201:
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'

Acceptance Criteria

• Complete OpenAPI 3.0 spec for all endpoints
• Interactive Swagger UI at /api-docs
• Request/response examples for all endpoints
• Authentication flow documented
• Error responses documented
• Auto-generated from JSDoc comments
• Versioned API documentation
• Test coverage > 80%

Priority

High - Critical for developer experience

---