openapi: 3.0.0
info:
  title: Auth Microservice API
  description: |
    Authentication and identity management microservice for the distributed architecture.
    Handles user registration, login, token validation, and session management.
    
    **Database**: emmanylcode_auth
    **Service ID**: auth-service
    **Version**: 1.0.0
  version: 1.0.0
  contact:
    name: Architecture Team
    email: support@emmanylcode.local
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

servers:
  - url: http://localhost/projects/SMS-MICROSERVICES/auth-service/public
    description: Development Auth Service
  - url: http://auth-service:3000
    description: Docker Development Auth Service
  - url: https://auth.emmanylcode.local
    description: Production Auth Service

security:
  - ApiKeyAuth: []

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API Key for service authentication
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Use the JWT token returned from /api/auth/login in the Authorization header as `Bearer <token>`

  schemas:
    User:
      type: object
      required:
        - id
        - name
        - email
        - phone
        - address
        - role_id
      properties:
        id:
          type: integer
          format: int64
          example: 1
          description: Unique user identifier
        name:
          type: string
          example: Odueso Emmanuel Jesutofunmi
          description: User full name
        email:
          type: string
          format: email
          example: superadmin001@example.com
          description: User email address
        phone:
          type: string
          example: 7051436088
          description: User phone number
        address:
          type: string
          example: Eposo Town Akaka Road Ode Remo
          description: User residential address
        role_id:
          type: integer
          example: 5
          description: User role identifier (5=Customer, 4=Admin, 3=Vendor)

    RegistrationRequest:
      type: object
      required:
        - name
        - email
        - password
        - phone
        - address
      properties:
        name:
          type: string
          minLength: 2
          maxLength: 255
          example: Odueso Emmanuel Jesutofunmi
          description: User full name
        email:
          type: string
          format: email
          example: superadmin001@example.com
          description: User email (must be unique)
        password:
          type: string
          format: password
          minLength: 8
          maxLength: 255
          example: SuperSecurePass123!
          description: User password (minimum 8 characters)
        phone:
          type: string
          minLength: 10
          maxLength: 20
          example: 7051436088
          description: User phone number
        address:
          type: string
          minLength: 5
          maxLength: 500
          example: Eposo Town Akaka Road Ode Remo
          description: User residential address
        role_id:
          type: integer
          example: 5
          description: User role (optional, defaults to 5 for customers)

    RegistrationResponse:
      type: object
      properties:
        message:
          type: string
          example: Registration successful
        user:
          $ref: '#/components/schemas/User'

    LoginRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
          example: superadmin001@example.com
          description: User email address
        password:
          type: string
          format: password
          example: SuperSecurePass123!
          description: User password

    LoginResponse:
      type: object
      properties:
        message:
          type: string
          example: Login successful
        user:
          $ref: '#/components/schemas/User'
        token:
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
          description: JWT authentication token

    ValidationRequest:
      type: object
      required:
        - token
      properties:
        token:
          type: string
          description: JWT token to validate

    ValidationResponse:
      type: object
      properties:
        message:
          type: string
          example: Token is valid

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
        field:
          type: string
          description: Field with error (if applicable)
        details:
          type: object
          description: Additional error details

    ServiceStatus:
      type: object
      properties:
        service:
          type: string
          example: auth-microservice
        status:
          type: string
          example: running
        version:
          type: string
          example: 1.0.0
        database:
          type: string
          example: emmanylcode_auth
        timestamp:
          type: string
          format: date-time
          example: 2024-05-26 14:30:00

paths:
  /:
    get:
      summary: Service Health Check
      description: Returns the health status of the Auth Microservice
      operationId: healthCheck
      security: []
      tags:
        - Health
      responses:
        '200':
          description: Service is running
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceStatus'
        '503':
          description: Service unavailable

  /api/auth/register:
    post:
      summary: Register a new user
      description: |
        Create a new user account. This endpoint validates input data,
        checks for duplicate emails, hashes the password, and persists
        the user to the emmanylcode_auth database.
        
        **Validation Rules**:
        - Email must be valid and unique
        - Password must be at least 8 characters
        - Phone and address are required
        
        **Database**: emmanylcode_auth (users table)
      operationId: registerUser
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegistrationRequest'
            examples:
              successful:
                summary: Valid Registration
                value:
                  name: Odueso Emmanuel Jesutofunmi
                  email: superadmin001@example.com
                  password: SuperSecurePass123!
                  phone: 7051436088
                  address: Eposo Town Akaka Road Ode Remo
                  role_id: 5
      responses:
        '201':
          description: User registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationResponse'
              examples:
                success:
                  summary: Registration Success
                  value:
                    message: Registration successful
                    user:
                      id: 1
                      name: Odueso Emmanuel Jesutofunmi
                      email: superadmin001@example.com
                      phone: 7051436088
                      address: Eposo Town Akaka Road Ode Remo
                      role_id: 5
        '400':
          description: Bad Request - Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingField:
                  summary: Missing Required Field
                  value:
                    error: Missing required field
                    field: password
                invalidEmail:
                  summary: Invalid Email Format
                  value:
                    error: Invalid email format
                    field: email
        '409':
          description: Conflict - Email already registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                emailExists:
                  summary: Email Already Exists
                  value:
                    error: Email already registered
                    field: email
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                databaseError:
                  summary: Database Error
                  value:
                    error: Database error
                    message: An error occurred while processing your request

  /api/auth/login:
    post:
      summary: Login user
      description: |
        Authenticate a user with email and password.
        Returns user details and JWT token on successful login.
      operationId: loginUser
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
            examples:
              successful:
                summary: Valid Login
                value:
                  email: superadmin001@example.com
                  password: SuperSecurePass123!
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
              examples:
                success:
                  summary: Login Success
                  value:
                    message: Login successful
                    user:
                      id: 1
                      name: Odueso Emmanuel Jesutofunmi
                      email: superadmin001@example.com
                      phone: 7051436088
                      address: Eposo Town Akaka Road Ode Remo
                      role_id: 5
                    token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        '400':
          description: Bad Request - Missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidCredentials:
                  summary: Invalid Email or Password
                  value:
                    error: Invalid email or password
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/auth/validate-token:
    post:
      summary: Validate authentication token
      description: |
        Verify if a JWT token is valid and not expired.
        Used by other microservices to validate tokens.
      operationId: validateToken
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidationRequest'
      responses:
        '200':
          description: Token is valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResponse'
        '400':
          description: Bad Request - Token missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Token invalid or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/auth/roles:
    get:
      summary: List roles
      description: Returns a list of roles defined in the auth service
      operationId: listRoles
      tags:
        - Authentication
      responses:
        '200':
          description: Roles list
          content:
            application/json:
              schema:
                type: object
                properties:
                  roles:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                        slug:
                          type: string

  /api/auth/statuses:
    get:
      summary: List statuses
      description: Returns a list of statuses defined in the auth service
      operationId: listStatuses
      tags:
        - Authentication
      responses:
        '200':
          description: Statuses list
          content:
            application/json:
              schema:
                type: object
                properties:
                  statuses:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                        slug:
                          type: string

tags:
  - name: Health
    description: Service health and status endpoints
  - name: Authentication
    description: User registration, login, and token validation
