/samples:
  get:
    summary: all samples in overview
    description: 'Auth: all, levels: read, write, maintain, dev, admin'
    x-doc: returns only samples with status 10
    tags:
      - /sample
    parameters:
      - name: status
        description: 'values: validated|new|all, defaults to validated'
        in: query
        schema:
          type: string
        example: all
      - name: from-id
        description: first id of the requested page, if not given the results are displayed from start
        in: query
        schema:
          type: string
        example: 5ea0450ed851c30a90e70894
      - name: to-page
        description: relative change of pages, use negative values to get back, defaults to 0, works only together with page-size
        in: query
        schema:
          type: string
        example: 1
      - name: page-size
        description: number of items per page
        in: query
        schema:
          type: string
        example: 30
      - name: sort
        description: sorting of results, in format 'key-asc/desc'
        in: query
        schema:
          type: string
        example: color-asc
      - name: csv
        description: output as csv
        in: query
        schema:
          type: boolean
        example: false
      - name: fields
        description: the fields to include in the output as array, defaults to ['_id','number','type','batch','material_id','color','condition','note_id','user_id','added']
        in: query
        schema:
         type: string
        example: '&fields[]=number&fields[]=batch'
    responses:
      200:
        description: samples overview (if the csv parameter is set, this is in CSV instead of JSON format)
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: 'api.yaml#/components/schemas/SampleRefs'
      400:
        $ref: 'api.yaml#/components/responses/400'
      401:
        $ref: 'api.yaml#/components/responses/401'
      404:
        $ref: 'api.yaml#/components/responses/404'
      500:
        $ref: 'api.yaml#/components/responses/500'

/samples/{state}:
  parameters:
    - $ref: 'api.yaml#/components/parameters/State'
  get:
    summary: all new/deleted samples in overview
    description: 'Auth: basic, levels: maintain, admin'
    x-doc: returns only samples with status 0/-1
    tags:
      - /sample
    responses:
      200:
        description: samples overview
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: 'api.yaml#/components/schemas/SampleRefs'
      401:
        $ref: 'api.yaml#/components/responses/401'
      500:
        $ref: 'api.yaml#/components/responses/500'

/samples/count:
  get:
    summary: total number of samples
    description: 'Auth: all, levels: read, write, maintain, dev, admin'
    tags:
      - /sample
    responses:
      200:
        description: sample count
        content:
          application/json:
            schema:
              properties:
                count:
                  type: number
                  example: 864
      500:
        $ref: 'api.yaml#/components/responses/500'

/sample/{id}:
  parameters:
    - $ref: 'api.yaml#/components/parameters/Id'
  get:
    summary: sample details
    description: 'Auth: all, levels: read, write, maintain, dev, admin<br>Returns validated as well as new measurements'
    x-doc: deleted samples are available only for maintain/admin
    tags:
      - /sample
    responses:
      200:
        description: samples details
        content:
          application/json:
            schema:
              $ref: 'api.yaml#/components/schemas/SampleDetail'
      400:
        $ref: 'api.yaml#/components/responses/400'
      401:
        $ref: 'api.yaml#/components/responses/401'
      404:
        $ref: 'api.yaml#/components/responses/404'
      500:
        $ref: 'api.yaml#/components/responses/500'
  put:
    summary: change sample
    description: 'Auth: basic, levels: write, maintain, dev, admin <br>Only maintain and admin are allowed to edit samples created by another user'
    x-doc: status is reset to 0 on any changes, deleted samples cannot be changed
    tags:
      - /sample
    security:
        - BasicAuth: []
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: 'api.yaml#/components/schemas/Sample'
    responses:
      200:
        description: samples details
        content:
          application/json:
            schema:
              $ref: 'api.yaml#/components/schemas/SampleRefs'
      400:
        $ref: 'api.yaml#/components/responses/400'
      401:
        $ref: 'api.yaml#/components/responses/401'
      403:
        $ref: 'api.yaml#/components/responses/403'
      404:
        $ref: 'api.yaml#/components/responses/404'
      500:
        $ref: 'api.yaml#/components/responses/500'
  delete:
    summary: delete sample
    description: 'Auth: basic, levels: write, maintain, dev, admin <br>Only maintain and admin are allowed to edit samples created by another user'
    x-doc: sets status to -1, notes and references to this sample are also kept, only note_fields are updated accordingly
    tags:
      - /sample
    security:
      - BasicAuth: []
    responses:
      200:
        $ref: 'api.yaml#/components/responses/Ok'
      400:
        $ref: 'api.yaml#/components/responses/400'
      401:
        $ref: 'api.yaml#/components/responses/401'
      403:
        $ref: 'api.yaml#/components/responses/403'
      404:
        $ref: 'api.yaml#/components/responses/404'
      500:
        $ref: 'api.yaml#/components/responses/500'

/sample/restore/{id}:
  parameters:
    - $ref: 'api.yaml#/components/parameters/Id'
  put:
    summary: restore sample
    description: 'Auth: basic, levels: maintain, admin'
    x-doc: status is set to 0
    tags:
      - /sample
    security:
      - BasicAuth: []
    responses:
      200:
        $ref: 'api.yaml#/components/responses/Ok'
      401:
        $ref: 'api.yaml#/components/responses/401'
      403:
        $ref: 'api.yaml#/components/responses/403'
      404:
        $ref: 'api.yaml#/components/responses/404'
      500:
        $ref: 'api.yaml#/components/responses/500'

/sample/validate/{id}:
  parameters:
    - $ref: 'api.yaml#/components/parameters/Id'
  put:
    summary: set sample status to validated
    description: 'Auth: basic, levels: maintain, admin'
    x-doc: status is set to 10
    tags:
      - /sample
    security:
      - BasicAuth: []
    responses:
      200:
        $ref: 'api.yaml#/components/responses/Ok'
      400:
        $ref: 'api.yaml#/components/responses/400'
      401:
        $ref: 'api.yaml#/components/responses/401'
      403:
        $ref: 'api.yaml#/components/responses/403'
      404:
        $ref: 'api.yaml#/components/responses/404'
      500:
        $ref: 'api.yaml#/components/responses/500'

/sample/new:
  post:
    summary: add sample
    description: 'Auth: basic, levels: write, maintain, dev, admin.   Number property is only for admin when adding existing samples'
    x-doc: 'Adds status: 0 automatically'
    tags:
      - /sample
    security:
      - BasicAuth: []
    requestBody:
      required: true
      content:
        application/json:
          schema:
            allOf:
              - $ref: 'api.yaml#/components/schemas/Sample'
            properties:
              number:
                type: string
                readOnly: false
    responses:
      200:
        description: samples details
        content:
          application/json:
            schema:
              $ref: 'api.yaml#/components/schemas/SampleRefs'
      400:
        $ref: 'api.yaml#/components/responses/400'
      401:
        $ref: 'api.yaml#/components/responses/401'
      403:
        $ref: 'api.yaml#/components/responses/403'
      500:
        $ref: 'api.yaml#/components/responses/500'

/sample/notes/fields:
  get:
    summary: list all existing field names for custom notes fields
    description: 'Auth: all, levels: read, write, maintain, dev, admin'
    x-doc: integrity has to be ensured
    tags:
      - /sample
    responses:
      200:
        description: field names and quantity of usage
        content:
          application/json:
            schema:
              type: array
              items:
                properties:
                  name:
                    type: string
                  qty:
                    type: number
                    example: 20
      401:
        $ref: 'api.yaml#/components/responses/401'
      500:
        $ref: 'api.yaml#/components/responses/500'