catalyst/definition/enterprise/groups.yaml

swagger: "2.0"
info: { version: "", title: "" }

paths:
  /groups:
    get:
      tags: [ "groups" ]
      summary: "List groups"
      operationId: "listGroups"
      responses:
        "200":
          description: "successful operation"
          schema: { type: array, items: { $ref: "#/definitions/Group" } }
      security: [ { roles: [ "group:read" ] } ]
    post:
      tags: [ "groups" ]
      summary: "Create a new group"
      operationId: "createGroup"
      parameters:
        - { name: "group", in: "body", description: "New group", required: true, schema: { $ref: "#/definitions/GroupForm" } }
      responses:
        "200":
          description: "successful operation"
          schema: { $ref: "#/definitions/GroupResponse" }
      security: [ { roles: [ "group:write" ] } ]

  /groups/{id}:
    get:
      tags: [ "groups" ]
      summary: "Get a single group"
      operationId: "getGroup"
      parameters:
        - { name: "id", in: "path", description: "Group ID", required: true, type: string }
      responses:
        "200":
          description: "successful operation"
          schema: { $ref: "#/definitions/GroupResponse" }
      security: [ { roles: [ "group:read" ] } ]
    put:
      tags: [ "groups" ]
      summary: "Update an existing group"
      operationId: "updateGroup"
      parameters:
        - { name: "id", in: "path", description: "Group ID", required: true, type: string }
        - { name: "group", in: "body", description: "Group object that needs to be added", required: true, schema: { $ref: "#/definitions/Group" } }
      responses:
        "200":
          description: "successful operation"
          schema: { $ref: "#/definitions/Group" }
      security: [ { roles: [ "group:write" ] } ]
    delete:
      tags: [ "groups" ]
      summary: "Delete a group"
      operationId: "deleteGroup"
      parameters:
        - { name: "id", in: "path", description: "Group ID", required: true, type: string }
      responses:
        "204": { description: "successful operation" }
      security: [ { roles: [ "group:write" ] } ]

definitions:
  GroupForm:
    type: object
    required: [ name, users ]
    properties:
      id: { type: string }
      name: { type: string }
      users: { type: array, items: { type: string } }

  Group:
    type: object
    required: [ name, users ]
    properties:
      name: { type: string }
      users: { type: array, items: { type: string } }


  GroupResponse:
    type: object
    required: [ id, name, users ]
    properties:
      id: { type: string }
      name: { type: string }
      users: { type: array, items: { type: string } }