openapi: 3.1.0
info:
  title: AOTG — Api on the Go
  version: 1.0.0
  description: |
    Generate test data and mock APIs.

    Pick field categories, define a schema, and receive random JSON —
    or create a mock REST endpoint for your app to test against.

    **Differentiators:**
    - Schema map with nested `object` / `array` fields
    - `seed` — reproducible output for CI and tests
    - `locale` — regional data (including `za` / `en-za` for South Africa)
    - OpenAPI import and optional CSV export

servers:
  - url: https://www.apionthego.com
    description: Production
  - url: http://localhost:3000
    description: Local development

paths:
  /v1/health:
    get:
      summary: Health check
      responses:
        "200":
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  service:
                    type: string
                    example: aotg
                  version:
                    type: string
                    example: 1.0.0

  /v1/types:
    get:
      summary: List supported field types
      responses:
        "200":
          description: Type catalog
          content:
            application/json:
              schema:
                type: object
                properties:
                  types:
                    type: array
                    items:
                      $ref: "#/components/schemas/TypeDefinition"
                  schemaFormat:
                    type: object

  /v1/generate:
    post:
      summary: Generate random data from a schema
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GenerateRequest"
            examples:
              basic:
                summary: User-like records
                value:
                  count: 5
                  schema:
                    id: uuid
                    fullName: name
                    email: email
                    age:
                      type: integer
                      min: 18
                      max: 65
                    active: boolean
                    joinedAt: datetime
              seeded:
                summary: Reproducible output for tests
                value:
                  count: 3
                  seed: 12345
                  locale: en
                  schema:
                    email: email
                    active: boolean
              southAfrica:
                summary: South African locale data
                value:
                  count: 2
                  locale: za
                  schema:
                    name: name
                    phone: phone
                    city: city

      responses:
        "200":
          description: Generated records (JSON) or CSV when format=csv
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenerateResponse"
            text/csv:
              schema:
                type: string
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /v1/import/openapi:
    post:
      summary: Convert OpenAPI 3 JSON into an AOTG schema
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  properties:
                    document:
                      type: object
                      additionalProperties: true
                - type: object
                  additionalProperties: true
            examples:
              componentSchema:
                summary: From components.schemas
                value:
                  document:
                    openapi: "3.0.0"
                    components:
                      schemas:
                        User:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                            email:
                              type: string
                              format: email
      responses:
        "200":
          description: Converted AOTG schema
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  schema:
                    $ref: "#/components/schemas/SchemaMap"
                  fieldCount:
                    type: integer
        "400":
          description: Invalid OpenAPI or unsupported schema
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /v1/presets:
    get:
      summary: List preset schemas
      responses:
        "200":
          description: Available presets

  /v1/presets/{id}/generate:
    post:
      summary: Generate data from a preset schema
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            enum: [user, product, catalogItem, address, employee, order]
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PresetGenerateRequest"
      responses:
        "200":
          description: Generated records
        "404":
          description: Preset not found

  /v1/examples:
    get:
      summary: Example product/category/brand lists
      responses:
        "200":
          description: Example lists

  /v1/apis/options:
    get:
      summary: Mock API method and auth options
      responses:
        "200":
          description: Supported methods and auth types

  /v1/apis:
    get:
      summary: List your mock APIs
      parameters:
        - $ref: "#/components/parameters/OwnerToken"
      responses:
        "200":
          description: Owner's mock APIs
        "401":
          description: Missing owner token
    post:
      summary: Create a unique mock API
      parameters:
        - $ref: "#/components/parameters/OwnerToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateMockApiRequest"
      responses:
        "201":
          description: Mock API created with ownerToken
        "400":
          description: Invalid request

  /v1/apis/{idOrSlug}:
    delete:
      summary: Delete your mock API
      parameters:
        - name: idOrSlug
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/OwnerToken"
      responses:
        "200":
          description: Deleted
        "401":
          description: Missing owner token
        "403":
          description: Not the owner
        "404":
          description: Not found

  /mock/{slug}:
    get:
      summary: Call a generated mock API
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Generated payload
        "401":
          description: Auth failed
        "404":
          description: Not found or expired
        "405":
          description: Method not allowed

components:
  parameters:
    OwnerToken:
      name: X-AOTG-Owner-Token
      in: header
      required: false
      description: Required to list/delete (and recommended on create). Identifies API ownership.
      schema:
        type: string

  schemas:
    TypeDefinition:
      type: object
      properties:
        id:
          type: string
          example: email
        description:
          type: string
        valueType:
          type: string
          enum: [string, number, boolean]
        config:
          nullable: true
          type: object

    SchemaMap:
      type: object
      additionalProperties:
        oneOf:
          - type: string
            description: Type id (e.g. email, uuid, boolean)
          - type: object
            properties:
              type:
                type: string
                description: Field type, including object or array
              min:
                type: number
              max:
                type: number
              fractionDigits:
                type: integer
              sentences:
                type: integer
              examples:
                type: array
                items:
                  type: string
              fields:
                $ref: "#/components/schemas/SchemaMap"
              properties:
                $ref: "#/components/schemas/SchemaMap"
              items:
                description: Array item type string or object/array field spec
                oneOf:
                  - type: string
                  - type: object
                    additionalProperties: true
              minItems:
                type: integer
              maxItems:
                type: integer

    GenerateRequest:
      type: object
      required: [schema]
      properties:
        count:
          type: integer
          minimum: 1
          maximum: 1000
          default: 1
        seed:
          type: number
        locale:
          type: string
          default: en
        format:
          type: string
          enum: [json, csv]
          default: json
        schema:
          $ref: "#/components/schemas/SchemaMap"

    PresetGenerateRequest:
      type: object
      properties:
        count:
          type: integer
          minimum: 1
          maximum: 1000
          default: 1
        seed:
          type: number
        locale:
          type: string
          default: en

    CreateMockApiRequest:
      type: object
      required: [schema]
      properties:
        name:
          type: string
        method:
          type: string
          enum: [GET, POST, PUT, PATCH, DELETE]
        auth:
          type: object
          properties:
            type:
              type: string
              enum: [none, bearer, apiKey, basic]
            token:
              type: string
            key:
              type: string
            header:
              type: string
            username:
              type: string
            password:
              type: string
        count:
          type: integer
          minimum: 1
          maximum: 1000
        locale:
          type: string
        seed:
          type: number
        ownerToken:
          type: string
        schema:
          $ref: "#/components/schemas/SchemaMap"

    GenerateResponse:
      type: object
      properties:
        meta:
          type: object
          properties:
            count:
              type: integer
            seed:
              nullable: true
              type: number
            locale:
              type: string
            fields:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  type:
                    type: string
        data:
          type: array
          items:
            type: object
            additionalProperties: true

    Error:
      type: object
      properties:
        error:
          type: string
        hint:
          type: string
