openapi: 3.0.3
info:
  title: Firebase Serverless REST API Demo
  version: 1.8.1
  description: >
    OpenAPI specification for the deployed Firebase Cloud Functions REST API.

servers:
  - url: https://firebase.stephendaly.dev
    description: Production

tags:
  - name: Health
    description: Health and availability checks
  - name: Comments
    description: Comment creation and retrieval

paths:
  /api/health:
    get:
      tags:
        - Health
      summary: Health check
      description: Returns API health status.
      operationId: getHealth
      responses:
        '200':
          description: API is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              examples:
                healthy:
                  value:
                    ok: true
                    message: API is running

  /api/comments:
    get:
      tags:
        - Comments
      summary: Get comments
      description: Returns stored comments.
      operationId: getComments
      responses:
        '200':
          description: Comments returned successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Comment'
              examples:
                exampleList:
                  value:
                    - id: example-id-1
                      handle: "@exampleuser"
                      text: "Hello world"
                      createdAt: "2026-02-07T20:20:25.524Z"
                    - id: example-id-2
                      handle: "@anotheruser"
                      text: "Second comment"
                      createdAt: "2026-02-07T20:21:10.000Z"

    post:
      tags:
        - Comments
      summary: Create comment
      description: Creates a new comment.
      operationId: createComment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCommentRequest'
            examples:
              valid:
                value:
                  handle: "@trailrunner23"
                  text: "Great run today!"
      responses:
        '201':
          description: Comment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCommentResponse'
              examples:
                created:
                  value:
                    id: "generated-comment-id"
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  value:
                    error: Validation failed

components:
  schemas:
    HealthResponse:
      type: object
      required:
        - ok
        - message
      properties:
        ok:
          type: boolean
          example: true
        message:
          type: string
          example: API is running

    Comment:
      type: object
      required:
        - id
        - handle
        - text
        - createdAt
      properties:
        id:
          type: string
          example: example-id-1
        handle:
          type: string
          example: "@exampleuser"
        text:
          type: string
          example: "Hello world"
        createdAt:
          type: string
          format: date-time
          example: "2026-02-07T20:20:25.524Z"

    CreateCommentRequest:
      type: object
      required:
        - handle
        - text
      properties:
        handle:
          type: string
          example: "@trailrunner23"
        text:
          type: string
          example: "Great run today!"

    CreateCommentResponse:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          example: "generated-comment-id"

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: Validation failed