user.yaml

get:
  operationId: userSearch
  tags: [user]
  summary: Get a list of users
  description: |
    This allows you to search for users and get details about the user. The search filter attributes are all optional.   
    The number of users returned is 5 by default, if the limit query parameter is not provided.
    This endpoint is only available to superusers to avoid leaking information about users to other users.

  responses:
    '200':
      $ref: ../components/responses/user-list.yaml
    default:
      $ref: ../components/responses/problem.yaml
  parameters:
    - name: search
      in: query
      description: |
        Will search `username`, `firstname`, `lastname` and `preferred_name` for non exact matches.
      schema:
        type: string
    - name: filter
      in: query
      description: |
        Json encoded object of fields and values to filter users on. \
        For example, to get user with username `jcoles`: \
        `filter=%7b%22username%22%3a%22jcoles%22%7d`
      schema:
        type: object
        properties:
          externalId:
            type: string
            example: 501
          username:
            type: string
            example: jreed
          email:
            type: string
            example: jreed@schoolbox.com.au
          year:
            description: A Year level to filter users with.
            oneOf:
              - type: object
                properties:
                  id:
                    type: integer
                    description: The DB identifier of the Year Level.
                    example: 6
              - type: object
                properties:
                  name:
                    type: string
                    description: The name of the Year Level, may not be unique.
                    example: Year 6
          role:
            description: A role to filter users with.
            oneOf:
              - type: object
                properties:
                  id:
                    type: integer
                    description: The DB identifier of the Role.
                    example: 1
              - type: object
                properties:
                  name:
                    type: string
                    description: The name of the Role, may not be unique.
                    example: Staff
          roleType:
            type: string
            enum:
              - student
              - staff
              - parent
              - guest
          campus:
            description: A campus to filter users with.
            oneOf:
              - type: object
                properties:
                  id:
                    type: integer
                    description: The DB identifier of the Campus.
                    example: 6
              - type: object
                properties:
                  name:
                    type: string
                    description: The name of the Campus, may not be unique.
                    example: Senior
    - $ref: ../components/parameters/cursor.yaml
    - $ref: ../components/parameters/limit.yaml
post:
  operationId: userPost
  tags: [user]
  summary: Create a user
  description: |
    This can be used to create a new user in the system.  This can only be completed by a superuser.  
    
    The minimum fields required to create a user are:
    ```
    "username": "rwhite",
    "role": {
      "id": 4
    },
    "campus": [
      {
        "id": 1
      }
    ],
    "firstName": "Rebecca"
    }
    ```
  responses:
    '201':
      $ref: ../components/responses/user-item.yaml
  requestBody:
    $ref: ../components/requestBodies/user-item.yaml