openapi: 3.1.0
info:
  title: Apache APISIX Admin Consumer Groups API
  description: The Apache APISIX Admin API provides a RESTful interface to dynamically control and configure your deployed Apache APISIX instance. It allows management of routes, services, upstreams, consumers, SSL certificates, global rules, plugin configurations, consumer groups, secrets, and more. By default, the Admin API listens on port 9180 and requires API key authentication via the X-API-KEY header.
  version: 3.14.0
  contact:
    name: Apache APISIX
    url: https://apisix.apache.org
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: http://127.0.0.1:9180/apisix/admin
  description: Default local Admin API server
security:
- apiKey: []
tags:
- name: Consumer Groups
  description: Manage consumer groups for shared plugin configurations.
paths:
  /consumer_groups:
    get:
      operationId: listConsumerGroups
      summary: Apache APISIX List All Consumer Groups
      description: Fetches a list of all configured consumer groups.
      tags:
      - Consumer Groups
      responses:
        '200':
          description: Successful response with list of consumer groups.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
  /consumer_groups/{group_id}:
    get:
      operationId: getConsumerGroup
      summary: Apache APISIX Get a Consumer Group
      description: Fetches the specified consumer group by its ID.
      tags:
      - Consumer Groups
      parameters:
      - $ref: '#/components/parameters/ConsumerGroupId'
      responses:
        '200':
          description: Successful response with consumer group details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceResponse'
        '404':
          description: Consumer group not found.
    put:
      operationId: createOrUpdateConsumerGroup
      summary: Apache APISIX Create or Update a Consumer Group
      description: Creates a consumer group with the specified ID, or updates it if it already exists.
      tags:
      - Consumer Groups
      parameters:
      - $ref: '#/components/parameters/ConsumerGroupId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsumerGroup'
      responses:
        '200':
          description: Consumer group updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceResponse'
        '201':
          description: Consumer group created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceCreated'
    patch:
      operationId: patchConsumerGroup
      summary: Apache APISIX Patch a Consumer Group
      description: Updates partial attributes of the specified consumer group.
      tags:
      - Consumer Groups
      parameters:
      - $ref: '#/components/parameters/ConsumerGroupId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsumerGroup'
      responses:
        '200':
          description: Consumer group patched successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceResponse'
    delete:
      operationId: deleteConsumerGroup
      summary: Apache APISIX Delete a Consumer Group
      description: Removes the specified consumer group.
      tags:
      - Consumer Groups
      parameters:
      - $ref: '#/components/parameters/ConsumerGroupId'
      responses:
        '200':
          description: Consumer group deleted successfully.
        '404':
          description: Consumer group not found.
components:
  schemas:
    ResourceResponse:
      type: object
      description: Standard response wrapper for a single resource.
      properties:
        key:
          type: string
          description: The etcd key path for the resource.
        value:
          type: object
          description: The resource configuration.
        modifiedIndex:
          type: integer
          description: The etcd modification index.
        createdIndex:
          type: integer
          description: The etcd creation index.
    ResourceCreated:
      type: object
      description: Response wrapper for a newly created resource.
      properties:
        key:
          type: string
          description: The etcd key path for the created resource.
        value:
          type: object
          description: The created resource configuration.
    ConsumerGroup:
      type: object
      description: A Consumer Group is a set of plugins that can be applied to multiple consumers rather than configuring each consumer individually.
      properties:
        desc:
          type: string
          description: Description of the consumer group.
        plugins:
          type: object
          description: Plugin configuration shared among consumers in this group.
        labels:
          type: object
          additionalProperties:
            type: string
          description: Key-value pairs for categorization.
    ResourceList:
      type: object
      description: Standard response wrapper for a list of resources.
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/ResourceResponse'
          description: Array of resource entries.
        total:
          type: integer
          description: Total count of resources.
  parameters:
    ConsumerGroupId:
      name: group_id
      in: path
      required: true
      description: Unique identifier of the consumer group.
      schema:
        type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-KEY
      description: Admin API key for authentication.