definma-api/oas/user.yaml

/users:
  get:
    summary: TODO lists all users
    description: 'Auth: basic, levels: admin'
    tags:
      - /user
    security:
      - BasicAuth: []
    responses:
      200:
        description: user API key
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: 'oas.yaml#/components/schemas/User'
      401:
        $ref: 'oas.yaml#/components/responses/401'
      403:
        $ref: 'oas.yaml#/components/responses/403'
      500:
        $ref: 'oas.yaml#/components/responses/500'
/user/{name}:
  parameters:
    - $ref: 'oas.yaml#/components/parameters/Name'
  get:
    summary: TODO list user details
    description: 'Auth: basic, levels: read, write, maintain, dev get their own information without a name property specified, level: admin can get any user using the name parameter'
    tags:
      - /user
    security:
      - BasicAuth: []
    responses:
      200:
        description: user details
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: 'oas.yaml#/components/schemas/User'
      400:
        $ref: 'oas.yaml#/components/responses/400'
      401:
        $ref: 'oas.yaml#/components/responses/401'
      403:
        $ref: 'oas.yaml#/components/responses/403'
      404:
        $ref: 'oas.yaml#/components/responses/404'
      500:
        $ref: 'oas.yaml#/components/responses/500'
  put:
    summary: TODO change user details
    description: 'Auth: basic, levels: read, write, maintain, dev can change their own information (except level) without a name property specified, level: admin can change any user using the name parameter'
    tags:
      - /user
    security:
      - BasicAuth: []
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: 'oas.yaml#/components/schemas/User'
    responses:
      200:
        description: user details
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: 'oas.yaml#/components/schemas/User'
      400:
        $ref: 'oas.yaml#/components/responses/400'
      401:
        $ref: 'oas.yaml#/components/responses/401'
      403:
        $ref: 'oas.yaml#/components/responses/403'
      404:
        $ref: 'oas.yaml#/components/responses/404'
      500:
        $ref: 'oas.yaml#/components/responses/500'
  delete:
    summary: TODO delete user
    description: 'Auth: basic, levels: read, write, maintain, dev can delete their own account, level: admin can delete any user using the name parameter'
    tags:
      - /user
    security:
      - BasicAuth: []
    responses:
      200:
        $ref: 'oas.yaml#/components/responses/Ok'
      400:
        $ref: 'oas.yaml#/components/responses/400'
      401:
        $ref: 'oas.yaml#/components/responses/401'
      403:
        $ref: 'oas.yaml#/components/responses/403'
      404:
        $ref: 'oas.yaml#/components/responses/404'
      500:
        $ref: 'oas.yaml#/components/responses/500'
/user/key:
  get:
    summary: TODO get API key for the user
    description: 'Auth: basic, levels: read, write, maintain, dev, admin'
    tags:
      - /user
    security:
      - BasicAuth: []
    responses:
      200:
        description: user details
        content:
          application/json:
            schema:
              $ref: 'oas.yaml#/components/schemas/User'
      401:
        $ref: 'oas.yaml#/components/responses/401'
      500:
        $ref: 'oas.yaml#/components/responses/500'
/user/new:
  post:
    summary: TODO add new user
    description: 'Auth: basic, levels: admin'
    tags:
      - /user
    security:
      - BasicAuth: []
    requestBody:
      required: true
      content:
        application/json:
          schema:
            required:
              - email
              - name
              - pass
              - level
              - location
              - device_name
            allOf:
              - $ref: 'oas.yaml#/components/schemas/User'
    responses:
      200:
        description: user details
        content:
          application/json:
            schema:
              $ref: 'oas.yaml#/components/schemas/User'
      400:
        $ref: 'oas.yaml#/components/responses/400'
      401:
        $ref: 'oas.yaml#/components/responses/401'
      403:
        $ref: 'oas.yaml#/components/responses/403'
      500:
        $ref: 'oas.yaml#/components/responses/500'
/user/passreset:
  post:
    summary: TODO reset password and send mail to restore
    description: 'Auth: none'
    tags:
      - /user
    security: []
    requestBody:
      required: true
      description: mail saved in user profile to provide authentication
      content:
        application/json:
          schema:
            $ref: 'oas.yaml#/components/schemas/Email'
    responses:
      200:
        $ref: 'oas.yaml#/components/responses/Ok'
      401:
        $ref: 'oas.yaml#/components/responses/401'
      500:
        $ref: 'oas.yaml#/components/responses/500'