get:
    summary: Returns a list of (optionally filtered) memberships.
    description: Returns the list of memberships which are visible to the current user or any of it's assumed roles.
        The list can optionally be filtered by either the `partnerUuid` or the `memberNumber` - not both at the same time.
    tags:
        - hs-office-memberships
    operationId: listMemberships
    parameters:
        - $ref: './auth.yaml#/components/parameters/currentUser'
        - $ref: './auth.yaml#/components/parameters/assumedRoles'
        - name: partnerUuid
          in: query
          required: false
          schema:
              type: string
              format: uuid
          description: UUID of the business partner, exclusive to `memberNumber`.
        - name: memberNumber
          in: query
          required: false
          schema:
              type: integer
          description: Member number, exclusive to `partnerUuid`.
    responses:
        "200":
            description: OK
            content:
                'application/json':
                    schema:
                        type: array
                        items:
                            $ref: './hs-office-membership-schemas.yaml#/components/schemas/HsOfficeMembership'
        "401":
            $ref: './error-responses.yaml#/components/responses/Unauthorized'
        "403":
            $ref: './error-responses.yaml#/components/responses/Forbidden'

post:
    summary: Adds a new membership.
    tags:
        - hs-office-memberships
    operationId: addMembership
    parameters:
        - $ref: './auth.yaml#/components/parameters/currentUser'
        - $ref: './auth.yaml#/components/parameters/assumedRoles'
    requestBody:
        description: A JSON object describing the new membership.
        required: true
        content:
            application/json:
                schema:
                    $ref: '/hs-office-membership-schemas.yaml#/components/schemas/HsOfficeMembershipInsert'
    responses:
        "201":
            description: Created
            content:
                'application/json':
                    schema:
                        $ref: './hs-office-membership-schemas.yaml#/components/schemas/HsOfficeMembership'
        "401":
            $ref: './error-responses.yaml#/components/responses/Unauthorized'
        "403":
            $ref: './error-responses.yaml#/components/responses/Forbidden'
        "409":
            $ref: './error-responses.yaml#/components/responses/Conflict'