kafka-ui/kafka-ui-contract/src/main/resources/swagger/kafka-ui-api.yaml

openapi: 3.0.0
info:
  description: Api Documentation
  version: 0.1.0
  title: Api Documentation
  termsOfService: urn:tos
  contact: {}
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
tags:
  - name: /api/clusters
servers:
  - url: /localhost

paths:
  /api/clusters:
    get:
      tags:
        - /api/clusters
      summary: getClusters
      operationId: getClusters
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Cluster'

  /api/clusters/{clusterName}/brokers:
    get:
      tags:
        - /api/clusters
      summary: getBrokers
      operationId: getBrokers
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Broker'

  /api/clusters/{clusterName}/metrics:
    get:
      tags:
        - /api/clusters
      summary: getClusterMetrics
      operationId: getClusterMetrics
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterMetrics'

  /api/clusters/{clusterName}/stats:
    get:
      tags:
        - /api/clusters
      summary: getClusterStats
      operationId: getClusterStats
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterStats'

  /api/clusters/{clusterName}/brokers/{id}/metrics:
    get:
      tags:
        - /api/clusters
      summary: getBrokersMetrics
      operationId: getBrokersMetrics
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrokerMetrics'

  /api/clusters/{clusterName}/topics:
    get:
      tags:
        - /api/clusters
      summary: getTopics
      operationId: getTopics
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Topic'
    post:
      tags:
        - /api/clusters
      summary: createTopic
      operationId: createTopic
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TopicFormData'
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Topic'

  /api/clusters/{clusterName}/topics/{topicName}:
    get:
      tags:
        - /api/clusters
      summary: getTopicDetails
      operationId: getTopicDetails
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
        - name: topicName
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopicDetails'
    patch:
      tags:
        - /api/clusters
      summary: updateTopic
      operationId: updateTopic
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
        - name: topicName
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TopicFormData'
      responses:
        200:
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Topic'

  /api/clusters/{clusterName}/topics/{topicName}/config:
    get:
      tags:
        - /api/clusters
      summary: getTopicConfigs
      operationId: getTopicConfigs
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
        - name: topicName
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TopicConfig'

  /api/clusters/{clusterName}/topics/{topicName}/messages:
    get:
      tags:
        - /api/clusters
      summary: getTopicMessages
      operationId: getTopicMessages
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
        - name: topicName
          in: path
          required: true
          schema:
            type: string
        - name: seekType
          in: query
          schema:
            $ref: "#/components/schemas/SeekType"
        - name: seekTo
          in: query
          schema:
            type: array
            items:
              type: string
          description: The format is [partition]::[offset] for specifying offsets or [partition]::[timstamp in millis] for specifying timestamps
        - name: limit
          in: query
          schema:
            type: integer
        - name: q
          in: query
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TopicMessage'

  /api/clusters/{clusterName}/consumer-groups/{id}:
    get:
      tags:
        - /api/clusters
      summary: get Consumer Group By Id
      operationId: getConsumerGroup
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsumerGroupDetails'

  /api/clusters/{clusterName}/consumerGroups:
    get:
      tags:
        - /api/clusters
      summary: get all ConsumerGroups
      operationId: getConsumerGroups
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsumerGroup'

  /api/clusters/{clusterName}/schemas:
    get:
      tags:
        - /api/clusters
      summary: get all schemas from Schema Registry service
      operationId: getSchemas
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

  /api/clusters/{clusterName}/schemas/{schemaName}:
    delete:
      tags:
        - /api/clusters
      summary: delete schema from Schema Registry service
      operationId: deleteSchema
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
        - name: schemaName
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
        404:
          description: Not found

  /api/clusters/{clusterName}/schemas/{schemaName}/versions:
    get:
      tags:
        - /api/clusters
      summary: get all version of schema from Schema Registry service
      operationId: getSchemaVersions
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
        - name: schemaName
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
    post:
      tags:
        - /api/clusters
      summary: create a new subject schema
      operationId: createNewSchema
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
        - name: schemaName
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewSchemaSubject'
      responses:
        200:
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaSubject'
        400:
          description: Bad request

  /api/clusters/{clusterName}/schemas/{schemaName}/latest:
    get:
      tags:
        - /api/clusters
      summary: get the latest schema from Schema Registry service
      operationId: getLatestSchemaByVersion
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
        - name: schemaName
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SchemaSubject'
    delete:
      tags:
        - /api/clusters
      summary: delete the latest schema from schema registry
      operationId: deleteLatestSchema
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
        - name: schemaName
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
        404:
          description: Not found


  /api/clusters/{clusterName}/schemas/{schemaName}/versions/{version}:
    get:
      tags:
        - /api/clusters
      summary: get schema by version from Schema Registry service
      operationId: getSchemaByVersion
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
        - name: schemaName
          in: path
          required: true
          schema:
            type: string
        - name: version
          in: path
          required: true
          schema:
            type: integer
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SchemaSubject'
    delete:
      tags:
        - /api/clusters
      summary: delete schema by version from schema registry
      operationId: deleteSchemaByVersion
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
        - name: schemaName
          in: path
          required: true
          schema:
            type: string
        - name: version
          in: path
          required: true
          schema:
            type: integer
      responses:
        200:
          description: OK
        404:
          description: Not found

  /api/clusters/{clusterName}/schemas/compatibility:
    get:
      tags:
        - /api/clusters
      summary: Get schema compatibility level globally
      operationId: getGlobalSchemaCompatibilityLevel
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompatibilityLevelResponse'
    put:
      tags:
        - /api/clusters
      summary: Update compatibility level globally
      operationId: updateGlobalSchemaCompatibilityLevel
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompatibilityLevel'
      responses:
        200:
          description: OK
        404:
          description: Not Found

  /api/clusters/{clusterName}/schemas/compatibility/{schemaName}:
    get:
      tags:
        - /api/clusters
      summary: Get schema compatibility level of specific schema
      operationId: getSchemaCompatibilityLevel
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
        - name: schemaName
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompatibilityLevelResponse'
    put:
      tags:
        - /api/clusters
      summary: Update compatibility level for specific schema.
      operationId: updateSchemaCompatibilityLevel
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
        - name: schemaName
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompatibilityLevel'
      responses:
        200:
          description: OK
        404:
          description: Not Found

  /api/clusters/{clusterName}/schemas/compatibility/{schemaName}/check:
    post:
      tags:
        - /api/clusters
      summary: Check compatibility of the schema.
      operationId: checkSchemaCompatibility
      parameters:
        - name: clusterName
          in: path
          required: true
          schema:
            type: string
        - name: schemaName
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewSchemaSubject'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompatibilityCheckResponse'
        404:
          description: Not Found

components:
  schemas:
    Cluster:
      type: object
      properties:
        name:
          type: string
        defaultCluster:
          type: boolean
        status:
          $ref: '#/components/schemas/ServerStatus'
        brokerCount:
          type: integer
        onlinePartitionCount:
          type: integer
        topicCount:
          type: integer
        bytesInPerSec:
          type: number
        bytesOutPerSec:
          type: number
      required:
        - id
        - name
        - status

    ServerStatus:
      type: string
      enum:
        - online
        - offline

    ClusterMetrics:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Metric'

    ClusterStats:
      type: object
      properties:
        brokerCount:
          type: integer
        zooKeeperStatus:
          type: integer
        activeControllers:
          type: integer
        onlinePartitionCount:
          type: integer
        offlinePartitionCount:
          type: integer
        inSyncReplicasCount:
          type: integer
        outOfSyncReplicasCount:
          type: integer
        underReplicatedPartitionCount:
          type: integer
        diskUsage:
          type: array
          items:
            $ref: '#/components/schemas/BrokerDiskUsage'

    BrokerDiskUsage:
      type: object
      properties:
        brokerId:
          type: integer
        segmentSize:
          type: integer
          format: int64
        segmentCount:
          type: integer
      required:
        - brokerId

    BrokerMetrics:
      type: object
      properties:
        segmentSize:
          type: integer
          format: int64
        segmentCount:
          type: integer
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/Metric'

    Topic:
      type: object
      properties:
        name:
          type: string
        internal:
          type: boolean
        partitionCount:
          type: integer
        replicationFactor:
          type: integer
        replicas:
          type: integer
        inSyncReplicas:
          type: integer
        segmentSize:
          type: integer
        segmentCount:
          type: integer
        underReplicatedPartitions:
          type: integer
        partitions:
          type: array
          items:
            $ref: "#/components/schemas/Partition"
      required:
        - name

    Replica:
      type: object
      properties:
        broker:
          type: integer
        leader:
          type: boolean
        inSync:
          type: boolean

    TopicDetails:
      type: object
      properties:
        name:
          type: string
        internal:
          type: boolean
        partitions:
          type: array
          items:
            $ref: "#/components/schemas/Partition"
        partitionCount:
          type: integer
        replicationFactor:
          type: integer
        replicas:
          type: integer
        inSyncReplicas:
          type: integer
        bytesInPerSec:
          type: number
        bytesOutPerSec:
          type: number
        segmentSize:
          type: integer
        segmentCount:
          type: integer
        underReplicatedPartitions:
          type: integer
      required:
        - name

    TopicConfig:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
        defaultValue:
          type: string
      required:
        - name

    TopicFormData:
      type: object
      properties:
        name:
          type: string
        partitions:
          type: integer
        replicationFactor:
          type: integer
        configs:
          type: object
          additionalProperties:
            type: string
      required:
        - name

    Broker:
      type: object
      properties:
        id:
          type: integer
        host:
          type: string
      required:
        - id

    ConsumerGroup:
      type: object
      properties:
        clusterId:
          type: string
        consumerGroupId:
            type: string
        numConsumers:
            type: integer
        numTopics:
            type: integer
      required:
        - clusterId
        - consumerGroupId

    TopicMessage:
      type: object
      properties:
        partition:
          type: integer
        offset:
          type: integer
          format: int64
        timestamp:
          type: string
          format: date-time
        timestampType:
          type: string
          enum:
            - NO_TIMESTAMP_TYPE
            - CREATE_TIME
            - LOG_APPEND_TIME
        key:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
        content:
          type: object
      required:
        - partition
        - offset
        - timestamp

    SeekType:
      type: string
      enum:
        - BEGINNING
        - OFFSET
        - TIMESTAMP

    Partition:
      type: object
      properties:
        partition:
          type: integer
        leader:
          type: integer
        replicas:
          type: array
          items:
            $ref: '#/components/schemas/Replica'
        offsetMax:
          type: integer
          format: int64
        offsetMin:
          type: integer
          format: int64
      required:
        - topic
        - partition
        - offsetMax
        - offsetMin

    ConsumerTopicPartitionDetail:
      type: object
      properties:
        consumerId:
          type: string
        topic:
          type: string
        host:
          type: string
        partition:
          type: integer
        currentOffset:
          type: integer
          format: int64
        endOffset:
          type: integer
          format: int64
        messagesBehind:
          type: integer
          format: int64
      required:
        - consumerId
        
    ConsumerGroupDetails:
      type: object
      properties:
        consumerGroupId:
          type: string
        consumers:
          type: array
          items:
            $ref: '#/components/schemas/ConsumerTopicPartitionDetail'
      required:
        - consumerGroupId

    Metric:
      type: object
      properties:
        name:
          type: string
        canonicalName:
          type: string
        params:
          type: string
          additionalProperties:
            type: string
        value:
          type: string
          additionalProperties:
            type: number

    SchemaSubject:
      type: object
      properties:
        subject:
          type: string
        version:
          type: string
        id:
          type: integer
        schema:
          type: string
      required:
        - id

    NewSchemaSubject:
      type: object
      properties:
        schema:
          type: string
      required:
        - schema

    CompatibilityLevel:
      type: object
      properties:
        compatibility:
          type: string
          enum:
            - BACKWARD
            - BACKWARD_TRANSITIVE
            - FORWARD
            - FORWARD_TRANSITIVE
            - FULL
            - FULL_TRANSITIVE
            - NONE
      required:
        - compatibility

    CompatibilityLevelResponse:
      type: object
      properties:
        compatibilityLevel:
          type: string
      required:
        - compatibilityLevel

    CompatibilityCheckResponse:
      type: object
      properties:
        isCompatible:
          type: boolean
      required:
        - isCompatible