# This code is auto generated, at src/scripts/generate-docs with the version 2.0.1 do NOT alter it directly

openapi: 3.0.0
info:
  title: Topic Explorer API
  version: 1.0.0
servers:
  - url: https://{hostname}/api
    variables:
      hostname:
        default: localhost
tags:
  - name: Levels
    description: Explore hierarchical levels of topics
  - name: Search
    description: Search across all topics by prefix
components:
  schemas:
    JSONAPIEnvelope:
      type: object
      properties:
        jsonapi:
          type: object
          properties:
            version:
              type: string
              example: '1.1'
        meta:
          type: object
          additionalProperties: true
          example: {}
      required:
        - jsonapi
        - meta
    JSONAPIError:
      type: object
      properties:
        status:
          type: string
          example: '500'
        title:
          type: string
          example: Internal Server Error
        detail:
          type: string
          example: >-
            The server encountered an unexpected condition that prevented it
            from fulfilling the request.
      required:
        - status
        - title
        - detail
    ErrorEnvelope:
      allOf:
        - $ref: '#/components/schemas/JSONAPIEnvelope'
        - type: object
          properties:
            errors:
              type: array
              items:
                $ref: '#/components/schemas/JSONAPIError'
    ChildNode:
      type: object
      properties:
        name:
          type: string
        has_more:
          type: boolean
      required:
        - name
        - has_more
    LevelsData:
      type: object
      properties:
        children:
          type: array
          items:
            $ref: '#/components/schemas/ChildNode'
      required:
        - children
    SearchResult:
      type: array
      items:
        type: string
  responses:
    ServiceUnavailable:
      description: Service Unavailable (Infrastructure error)
      content:
        text/plain:
          schema:
            type: string
            example: >-
              upstream connect error or disconnect/reset before headers. reset
              reason: connection failure
paths:
  /v2/mqtt/topics/levels:
    get:
      tags:
        - Levels
      security:
        - ApiKeyHeader: []
      summary: Get immediate children of a prefix
      description: Returns the child nodes for a given prefix.
      parameters:
        - name: prefix
          in: query
          required: false
          schema:
            type: string
          description: >-
            Path prefix (URL-encoded). Needs to be built by joining previous
            levels with '/'. If omitted, root level is assumed.
      responses:
        '200':
          description: List of child nodes wrapped in JSON:API envelope.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/JSONAPIEnvelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/LevelsData'
                    required:
                      - data
              example:
                jsonapi:
                  version: '1.1'
                data:
                  children:
                    - name: Germany
                      has_more: true
                    - name: France
                      has_more: true
                meta: {}
        '500':
          description: Internal error retrieving levels.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                jsonapi:
                  version: '1.1'
                errors:
                  - status: '500'
                    title: Internal Server Error
                    detail: levels error
                meta: {}
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v2/mqtt/topics/search:
    get:
      tags:
        - Search
      security:
        - ApiKeyHeader: []
      summary: Search topics by prefix
      description: Returns all topics matching a given prefix.
      parameters:
        - name: prefix
          in: query
          required: true
          schema:
            type: string
          description: Path prefix to search for (URL-encoded).
      responses:
        '200':
          description: Search results wrapped in JSON:API envelope.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/JSONAPIEnvelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/SearchResult'
              example:
                jsonapi:
                  version: '1.1'
                data:
                  - Earth/Germany/Berlin/
                  - Earth/Germany/Hamburg
                meta: {}
        '400':
          description: Missing prefix parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                jsonapi:
                  version: '1.1'
                errors:
                  - status: '400'
                    title: Bad Request
                    detail: missing prefix parameter
                meta: {}
        '500':
          description: Internal error during search.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                jsonapi:
                  version: '1.1'
                errors:
                  - status: '500'
                    title: Internal Server Error
                    detail: search error
                meta: {}
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
securityDefinitions:
  ApiKeyHeader:
    type: apiKey
    in: header
    name: Authorization
