splitted oas.yaml

2020-04-21 10:53:07 +02:00 · 2020-04-21 10:53:07 +02:00 · 5e22afd27d
commit 5e22afd27d
parent 54e01a3320
16 changed files with 1167 additions and 1137 deletions
--- a/oas.yaml
+++ b/oas.yaml
--- a/oas/condition.yaml
+++ b/oas/condition.yaml
@ -0,0 +1,69 @@
+/condition/{id}:
+  parameters:
+    - $ref: 'oas.yaml#/components/parameters/Id'
+  get:
+    summary: TODO condition by id
+    description: 'levels: read, write, maintain, dev, admin'
+    tags:
+      - /condition
+    responses:
+      200:
+        description: condition details
+        content:
+          application/json:
+            schema:
+              $ref: 'oas.yaml#/components/schemas/Condition'
+      400:
+        $ref: 'oas.yaml#/components/responses/400'
+      401:
+        $ref: 'oas.yaml#/components/responses/401'
+      404:
+        $ref: 'oas.yaml#/components/responses/404'
+      500:
+        $ref: 'oas.yaml#/components/responses/500'
+  put:
+    summary: TODO add/change condition
+    description: 'levels: write, maintain, dev, admin'
+    tags:
+      - /condition
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: 'oas.yaml#/components/schemas/Condition'
+    responses:
+      200:
+        description: condition details
+        content:
+          application/json:
+            schema:
+              $ref: 'oas.yaml#/components/schemas/Condition'
+      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 condition
+    description: 'levels: write, maintain, dev, admin'
+    tags:
+      - /condition
+    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'
--- a/oas/material.yaml
+++ b/oas/material.yaml
@ -0,0 +1,63 @@
+/material/{id}:
+  parameters:
+    - $ref: 'oas.yaml#/components/parameters/Id'
+  get:
+    summary: TODO get material details
+    description: 'levels: read, write, maintain, dev, admin'
+    tags:
+      - /material
+    responses:
+      200:
+        description: created material
+        content:
+          application/json:
+            schema:
+              $ref: 'oas.yaml#/components/schemas/Material'
+      400:
+        $ref: 'oas.yaml#/components/responses/400'
+      401:
+        $ref: 'oas.yaml#/components/responses/401'
+      500:
+        $ref: 'oas.yaml#/components/responses/500'
+  put:
+    summary: TODO add/change material
+    description: 'levels: write, maintain, dev, admin'
+    tags:
+      - /material
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: 'oas.yaml#/components/schemas/Material'
+    responses:
+      200:
+        description: material details
+        content:
+          application/json:
+            schema:
+              $ref: 'oas.yaml#/components/schemas/Material'
+      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'
+  delete:
+    summary: TODO delete material
+    description: 'levels: write, maintain, dev, admin'
+    tags:
+      - /material
+    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'
+      500:
+        $ref: 'oas.yaml#/components/responses/500'
--- a/oas/measurement.yaml
+++ b/oas/measurement.yaml
@ -0,0 +1,69 @@
+/measurement/{id}:
+  parameters:
+    - $ref: 'oas.yaml#/components/parameters/Id'
+  get:
+    summary: TODO measurement values by id
+    description: 'levels: read, write, maintain, dev, admin'
+    tags:
+      - /measurement
+    responses:
+      200:
+        description: measurement details
+        content:
+          application/json:
+            schema:
+              $ref: 'oas.yaml#/components/schemas/Measurement'
+      400:
+        $ref: 'oas.yaml#/components/responses/400'
+      401:
+        $ref: 'oas.yaml#/components/responses/401'
+      404:
+        $ref: 'oas.yaml#/components/responses/404'
+      500:
+        $ref: 'oas.yaml#/components/responses/500'
+  put:
+    summary: TODO add/change measurement
+    description: 'levels: write, maintain, dev, admin'
+    tags:
+      - /measurement
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: 'oas.yaml#/components/schemas/Measurement'
+    responses:
+      200:
+        description: measurement details
+        content:
+          application/json:
+            schema:
+              $ref: 'oas.yaml#/components/schemas/Measurement'
+      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 measurement
+    description: 'levels: write, maintain, dev, admin'
+    tags:
+      - /measurement
+    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'
--- a/oas/model.yaml
+++ b/oas/model.yaml
@ -0,0 +1,68 @@
+/model/{name}:
+  parameters:
+    - $ref: 'oas.yaml#/components/parameters/Name'
+  get:
+    summary: TODO get model data by name
+    description: 'levels: dev, admin'
+    tags:
+      - /model
+    responses:
+      200:
+        description: binary model data
+        content:
+          application/octet-stream:
+            schema:
+              type: string
+              format: binary
+      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 add/replace model data by name
+    description: 'levels: dev, admin'
+    tags:
+      - /model
+    requestBody:
+      required: true
+      description: binary model data
+      content:
+        application/json:
+          schema:
+            type: string
+            format: binary
+    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'
+  delete:
+    summary: TODO delete model data
+    description: 'levels: dev, admin'
+    tags:
+      - /model
+    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'
--- a/oas/oas.yaml
+++ b/oas/oas.yaml
@ -0,0 +1,74 @@
+openapi: 3.0.2
+
+
+info:
+  title: Digital fingerprint of plastics - API
+  version: 1.0.0
+  description: |
+    This API gives access to the project database.<br>
+    Access is restricted. Authentication can be obtained with HTTP Basic Auth using username and password. Data access methods can also be accessed using an API key at the URL ending like ?key=xxx<br>
+    There are a number of different user levels: <br>
+    <ul>
+      <li>read: read access to the samples database</li>
+      <li>write: write access to the samples database, users can change only the values they created</li>
+      <li>maintain: functions like changing templates, validating data, changing values of others</li>
+      <li>dev: handling machine learning models</li>
+      <li>admin: user administration</li>
+    </ul>
+
+
+
+servers:
+  - url: http://localhost:3000
+    description: local server
+  - url: https://digital-fingerprint-of-plastics-api.apps.de1.bosch-iot-cloud.com/
+    description: server on the BIC
+
+
+security:
+  - ApiKey: []
+  - BasicAuth: []
+
+
+tags:
+  - name: /
+  - name: /sample
+  - name: /material
+  - name: /condition
+  - name: /measurement
+  - name: /templates
+  - name: /model
+  - name: /user
+
+
+paths:
+  allOf:
+    - $ref: 'others.yaml'
+    - $ref: 'sample.yaml'
+    - $ref: 'material.yaml'
+    - $ref: 'condition.yaml'
+    - $ref: 'measurement.yaml'
+    - $ref: 'template.yaml'
+    - $ref: 'model.yaml'
+    - $ref: 'user.yaml'
+
+
+components:
+  parameters:
+    $ref: 'parameters.yaml'
+
+  schemas:
+    $ref: 'schemas.yaml'
+
+  responses:
+    $ref: 'responses.yaml'
+
+
+  securitySchemes:
+    BasicAuth:
+      type: http
+      scheme: basic
+    ApiKey:
+      type: apiKey
+      in: query
+      name: key
--- a/oas/others.yaml
+++ b/oas/others.yaml
@ -0,0 +1,18 @@
+/:
+  get:
+    summary: Root method
+    tags:
+      - /
+    security: []
+    responses:
+      200:
+        description: Server is working
+        content:
+          application/json:
+            schema:
+              properties:
+                message:
+                  type: string
+                  example: 'API server up and running!'
+      500:
+        $ref: 'oas.yaml#/components/responses/500'
--- a/oas/parameters.yaml
+++ b/oas/parameters.yaml
@ -0,0 +1,12 @@
+Id:
+  name: id
+  in: path
+  required: true
+  schema:
+    type: string
+Name:
+  name: name
+  in: path
+  required: true
+  schema:
+    type: string
--- a/oas/responses.yaml
+++ b/oas/responses.yaml
@ -0,0 +1,54 @@
+400:
+  description: Bad request
+  content:
+    application/json:
+      schema:
+        properties:
+          status:
+            type: string
+            example: 'Bad request'
+401:
+  description: Unauthorized
+  content:
+    application/json:
+      schema:
+        properties:
+          status:
+            type: string
+            example: 'Unauthorized'
+403:
+  description: Forbidden
+  content:
+    application/json:
+      schema:
+        properties:
+          status:
+            type: string
+            example: 'Forbidden'
+404:
+  description: Not found
+  content:
+    application/json:
+      schema:
+        properties:
+          status:
+            type: string
+            example: 'Not found'
+500:
+  description: Internal server error
+  content:
+    application/json:
+      schema:
+        properties:
+          status:
+            type: string
+            example: 'Internal server error'
+Ok:
+  description: request executed successfully
+  content:
+    application/json:
+      schema:
+        properties:
+          status:
+            type: string
+            example: OK
--- a/oas/sample.yaml
+++ b/oas/sample.yaml
@ -0,0 +1,108 @@
+/samples:
+  get:
+    summary: TODO all samples in overview
+    description: 'levels: read, write, maintain, dev, admin'
+    tags:
+      - /sample
+    responses:
+      200:
+        description: samples overview
+        content:
+          application/json:
+            schema:
+              $ref: 'oas.yaml#/components/schemas/Samples'
+      401:
+        $ref: 'oas.yaml#/components/responses/401'
+      500:
+        $ref: 'oas.yaml#/components/responses/500'
+/sample/{id}:
+  parameters:
+    - $ref: 'oas.yaml#/components/parameters/Id'
+  get:
+    summary: TODO sample details
+    description: 'levels: read, write, maintain, dev, admin'
+    tags:
+      - /sample
+    responses:
+      200:
+        description: samples details
+        content:
+          application/json:
+            schema:
+              $ref: 'oas.yaml#/components/schemas/SampleDetail'
+      400:
+        $ref: 'oas.yaml#/components/responses/400'
+      401:
+        $ref: 'oas.yaml#/components/responses/401'
+      404:
+        $ref: 'oas.yaml#/components/responses/404'
+      500:
+        $ref: 'oas.yaml#/components/responses/500'
+  put:
+    summary: TODO add/change sample
+    description: 'levels: write, maintain, dev, admin'
+    tags:
+      - /sample
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: 'oas.yaml#/components/schemas/Sample'
+    responses:
+      200:
+        description: samples details
+        content:
+          application/json:
+            schema:
+              $ref: 'oas.yaml#/components/schemas/SampleDetail'
+      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 sample
+    description: 'levels: write, maintain, dev, admin'
+    tags:
+      - /sample
+    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'
+/sample/notes/fields:
+  get:
+    summary: TODO list all existing field names for custom notes fields
+    description: 'levels: write, maintain, dev, admin'
+    tags:
+      - /sample
+    responses:
+      200:
+        description: field names and quantity of usage
+        content:
+          application/json:
+            schema:
+              properties:
+                name:
+                  type: string
+                qty:
+                  type: number
+                  example: 20
+      401:
+        $ref: 'oas.yaml#/components/responses/401'
+      500:
+        $ref: 'oas.yaml#/components/responses/500'
--- a/oas/schemas.yaml
+++ b/oas/schemas.yaml
@ -0,0 +1,164 @@
+Id:
+  type: string
+_Id:
+  properties:
+    _id:
+      allOf:
+        - $ref: 'oas.yaml#/components/schemas/Id'
+      readOnly: true
+Color:
+  properties:
+    color:
+      type: string
+SampleProperties:
+  properties:
+    sample_number:
+      type: string
+    type:
+      type: string
+    batch:
+      type: string
+    validated:
+      type: boolean
+
+Samples:
+  allOf:
+    - $ref: 'oas.yaml#/components/schemas/_Id'
+    - $ref: 'oas.yaml#/components/schemas/Color'
+    - $ref: 'oas.yaml#/components/schemas/SampleProperties'
+  properties:
+    material_id:
+      $ref: 'oas.yaml#/components/schemas/Id'
+    note_id:
+      $ref: 'oas.yaml#/components/schemas/Id'
+    user_id:
+      $ref: 'oas.yaml#/components/schemas/Id'
+Sample:
+  allOf:
+    - $ref: 'oas.yaml#/components/schemas/_Id'
+    - $ref: 'oas.yaml#/components/schemas/Color'
+    - $ref: 'oas.yaml#/components/schemas/SampleProperties'
+  properties:
+    material:
+      $ref: 'oas.yaml#/components/schemas/Material'
+    notes:
+      type: object
+      properties:
+        comments:
+          type: string
+        sample_references:
+          type: array
+          items:
+            $ref: 'oas.yaml#/components/schemas/Id'
+SampleDetail:
+  allOf:
+    - $ref: 'oas.yaml#/components/schemas/_Id'
+    - $ref: 'oas.yaml#/components/schemas/Color'
+    - $ref: 'oas.yaml#/components/schemas/SampleProperties'
+  properties:
+    material:
+      $ref: 'oas.yaml#/components/schemas/Material'
+    notes:
+      type: object
+      properties:
+        comments:
+          type: string
+        sample_references:
+          type: array
+          items:
+            $ref: 'oas.yaml#/components/schemas/Id'
+    conditions:
+      type: array
+      items:
+        $ref: 'oas.yaml#/components/schemas/Condition'
+
+Material:
+  allOf:
+    - $ref: 'oas.yaml#/components/schemas/_Id'
+  properties:
+    material_numbers:
+      type: array
+      items:
+        type: object
+        allOf:
+          - $ref: 'oas.yaml#/components/schemas/Color'
+        properties:
+          number:
+            type: number
+    material_group:
+      type: string
+    supplier:
+      type: string
+    material_name:
+      type: string
+    mineral:
+      type: number
+    glass_fiber:
+      type: number
+    carbon_fiber:
+      type: number
+
+Condition:
+  allOf:
+    - $ref: 'oas.yaml#/components/schemas/_Id'
+  properties:
+    sample_id:
+      $ref: 'oas.yaml#/components/schemas/Id'
+    parameters:
+      type: object
+    treatment_template:
+      $ref: 'oas.yaml#/components/schemas/Id'
+
+Measurement:
+  allOf:
+    - $ref: 'oas.yaml#/components/schemas/_Id'
+  properties:
+    condition_id:
+      $ref: 'oas.yaml#/components/schemas/Id'
+    values:
+      type: object
+    measurement_template:
+      $ref: 'oas.yaml#/components/schemas/Id'
+
+Template:
+  allOf:
+    - $ref: 'oas.yaml#/components/schemas/_Id'
+  properties:
+    name:
+      type: string
+    parameters:
+      type: array
+      items:
+        type: object
+        properties:
+          name:
+            type: string
+          range:
+            type: object
+
+Email:
+  required:
+    - email
+  properties:
+    email:
+      type: string
+      example: john.doe@bosch.com
+User:
+  allOf:
+    - $ref: 'oas.yaml#/components/schemas/_Id'
+    - $ref: 'oas.yaml#/components/schemas/Email'
+  properties:
+    name:
+      type: string
+      example: johndoe
+    levels:
+      type: array
+      items:
+        type: string
+        example: read
+    location:
+      type: string
+      example: Rng
+    device_name:
+      type: string
+      example: Alpha II
--- a/oas/template.yaml
+++ b/oas/template.yaml
@ -0,0 +1,242 @@
+/template/treatments:
+  get:
+    summary: TODO all available treatment methods
+    description: 'levels: read, write, maintain, dev, admin'
+    tags:
+      - /templates
+    security:
+      - BasicAuth: []
+    responses:
+      200:
+        description: list of treatments
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                $ref: 'oas.yaml#/components/schemas/Template'
+              example:
+                name: heat aging
+                parameters:
+                  - name: method
+                    range:
+                      - copper
+      401:
+        $ref: 'oas.yaml#/components/responses/401'
+      500:
+        $ref: 'oas.yaml#/components/responses/500'
+/templates/treatment/{name}:
+  parameters:
+    - $ref: 'oas.yaml#/components/parameters/Name'
+  get:
+    summary: TODO treatment method details
+    description: 'levels: read, write, maintain, admin'
+    tags:
+      - /templates
+    security:
+      - BasicAuth: []
+    responses:
+      200:
+        description: treatment details
+        content:
+          application/json:
+            schema:
+              allOf:
+                - $ref: 'oas.yaml#/components/schemas/Template'
+              example:
+                name: heat aging
+                parameters:
+                  - name: method
+                    range:
+                      - copper
+      400:
+        $ref: 'oas.yaml#/components/responses/400'
+      401:
+        $ref: 'oas.yaml#/components/responses/401'
+      404:
+        $ref: 'oas.yaml#/components/responses/404'
+      500:
+        $ref: 'oas.yaml#/components/responses/500'
+  put:
+    summary: TODO add/change treatment method
+    description: 'levels: maintain, admin'
+    tags:
+      - /templates
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: 'oas.yaml#/components/schemas/Template'
+            example:
+              name: heat aging
+              parameters:
+                - name: method
+                  range:
+                    - copper
+    responses:
+      200:
+        description: treatment details
+        content:
+          application/json:
+            schema:
+              allOf:
+                - $ref: 'oas.yaml#/components/schemas/Template'
+              example:
+                name: heat aging
+                parameters:
+                  - name: method
+                    range:
+                      - copper
+      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 treatment method
+    description: 'levels: maintain, admin'
+    tags:
+      - /templates
+    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'
+/template/measurements:
+  get:
+    summary: TODO all available measurement methods
+    description: 'levels: read, write, maintain, dev, admin'
+    tags:
+      - /templates
+    security:
+      - BasicAuth: []
+    responses:
+      200:
+        description: list of measurement methods
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                $ref: 'oas.yaml#/components/schemas/Template'
+              example:
+                name: humidity
+                parameters:
+                  - name: kf
+                    range:
+                      min: 0
+                      max: 2
+      401:
+        $ref: 'oas.yaml#/components/responses/401'
+      500:
+        $ref: 'oas.yaml#/components/responses/500'
+/templates/measurement/{name}:
+  parameters:
+    - $ref: 'oas.yaml#/components/parameters/Name'
+  get:
+    summary: TODO measurement method details
+    description: 'levels: read, write, maintain, admin'
+    tags:
+      - /templates
+    security:
+      - BasicAuth: []
+    responses:
+      200:
+        description: measurement details
+        content:
+          application/json:
+            schema:
+              allOf:
+                - $ref: 'oas.yaml#/components/schemas/Template'
+              example:
+                name: humidity
+                parameters:
+                  - name: kf
+                    range:
+                      min: 0
+                      max: 2
+      400:
+        $ref: 'oas.yaml#/components/responses/400'
+      401:
+        $ref: 'oas.yaml#/components/responses/401'
+      404:
+        $ref: 'oas.yaml#/components/responses/404'
+      500:
+        $ref: 'oas.yaml#/components/responses/500'
+  put:
+    summary: TODO add/change measurement method
+    description: 'levels: maintain, admin'
+    tags:
+      - /templates
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: 'oas.yaml#/components/schemas/Template'
+            example:
+              name: humidity
+              parameters:
+                - name: kf
+                  range:
+                    min: 0
+                    max: 2
+    responses:
+      200:
+        description: measurement details
+        content:
+          application/json:
+            schema:
+              allOf:
+                - $ref: 'oas.yaml#/components/schemas/Template'
+              example:
+                name: humidity
+                parameters:
+                  - name: kf
+                    range:
+                      min: 0
+                      max: 2
+      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 measurement method
+    description: 'levels: maintain, admin'
+    tags:
+      - /templates
+    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'
--- a/oas/user.yaml
+++ b/oas/user.yaml
@ -0,0 +1,170 @@
+/users:
+  get:
+    summary: TODO lists all users
+    description: '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: '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: '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
+    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: 'levels: read, write, maintain, dev can delete their own account, level: admin can delete any user using the name parameter'
+    tags:
+      - /user
+    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: '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: 'levels: admin'
+    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'
+      500:
+        $ref: 'oas.yaml#/components/responses/500'
+/user/passreset:
+  post:
+    summary: TODO reset password and send mail to restore
+    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'
--- a/package-lock.json
+++ b/package-lock.json
@ -4,6 +4,16 @@
  "lockfileVersion": 1,
  "requires": true,
  "dependencies": {
+    "@apidevtools/json-schema-ref-parser": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/@apidevtools/json-schema-ref-parser/-/json-schema-ref-parser-8.0.0.tgz",
+      "integrity": "sha512-n4YBtwQhdpLto1BaUCyAeflizmIbaloGShsPyRtFf5qdFJxfssj+GgLavczgKJFa3Bq+3St2CKcpRJdjtB4EBw==",
+      "requires": {
+        "@jsdevtools/ono": "^7.1.0",
+        "call-me-maybe": "^1.0.1",
+        "js-yaml": "^3.13.1"
+      }
+    },
    "@babel/code-frame": {
      "version": "7.8.3",
      "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.8.3.tgz",
@ -22,6 +32,11 @@
        "js-tokens": "^4.0.0"
      }
    },
+    "@jsdevtools/ono": {
+      "version": "7.1.2",
+      "resolved": "https://registry.npmjs.org/@jsdevtools/ono/-/ono-7.1.2.tgz",
+      "integrity": "sha512-qS/a24RA5FEoiJS9wiv6Pwg2c/kiUo3IVUQcfeM9JvsR6pM8Yx+yl/6xWYLckZCT5jpLNhslgjiA8p/XcGyMRQ=="
+    },
    "@sindresorhus/is": {
      "version": "0.14.0",
      "resolved": "https://registry.npmjs.org/@sindresorhus/is/-/is-0.14.0.tgz",
@ -338,6 +353,11 @@
        }
      }
    },
+    "call-me-maybe": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/call-me-maybe/-/call-me-maybe-1.0.1.tgz",
+      "integrity": "sha1-JtII6onje1y95gJQoV8DHBak1ms="
+    },
    "camelcase": {
      "version": "5.3.1",
      "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-5.3.1.tgz",
@ -1118,6 +1138,11 @@
      "resolved": "https://registry.npmjs.org/json-buffer/-/json-buffer-3.0.0.tgz",
      "integrity": "sha1-Wx85evx11ne96Lz8Dkfh+aPZqJg="
    },
+    "json-schema": {
+      "version": "0.2.5",
+      "resolved": "https://registry.npmjs.org/json-schema/-/json-schema-0.2.5.tgz",
+      "integrity": "sha512-gWJOWYFrhQ8j7pVm0EM8Slr+EPVq1Phf6lvzvD/WCeqkrx/f2xBI0xOsRRS9xCn3I4vKtP519dvs3TP09r24wQ=="
+    },
    "kareem": {
      "version": "2.3.1",
      "resolved": "https://registry.npmjs.org/kareem/-/kareem-2.3.1.tgz",
@ -1242,18 +1267,11 @@
      "integrity": "sha512-FM9nNUYrRBAELZQT3xeZQ7fmMOBg6nWNmJKTcgsJeaLstP/UODVpGsr5OhXhhXg6f+qtJ8uiZ+PUxkDWcgIXLw=="
    },
    "mkdirp": {
-      "version": "0.5.1",
-      "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.1.tgz",
-      "integrity": "sha1-MAV0OOrGz3+MR2fzhkjWaX11yQM=",
+      "version": "0.5.5",
+      "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.5.tgz",
+      "integrity": "sha512-NKmAlESf6jMGym1++R0Ra7wvhV+wFW63FaSOFPwRahvea0gMUcGUhVeAg/0BC0wiv9ih5NYPB1Wn1UEI1/L+xQ==",
      "requires": {
-        "minimist": "0.0.8"
-      },
-      "dependencies": {
-        "minimist": {
-          "version": "0.0.8",
-          "resolved": "https://registry.npmjs.org/minimist/-/minimist-0.0.8.tgz",
-          "integrity": "sha1-hX/Kv8M5fSYluCKCYuhqp6ARsF0="
-        }
+        "minimist": "^1.2.5"
      }
    },
    "mocha": {
@ -1333,6 +1351,21 @@
            "path-is-absolute": "^1.0.0"
          }
        },
+        "minimist": {
+          "version": "0.0.8",
+          "resolved": "https://registry.npmjs.org/minimist/-/minimist-0.0.8.tgz",
+          "integrity": "sha1-hX/Kv8M5fSYluCKCYuhqp6ARsF0=",
+          "dev": true
+        },
+        "mkdirp": {
+          "version": "0.5.1",
+          "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.1.tgz",
+          "integrity": "sha1-MAV0OOrGz3+MR2fzhkjWaX11yQM=",
+          "dev": true,
+          "requires": {
+            "minimist": "0.0.8"
+          }
+        },
        "ms": {
          "version": "2.1.1",
          "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.1.tgz",
@ -2425,15 +2458,6 @@
      "integrity": "sha512-r9S/ZyXu/Xu9q1tYlpsLIsa3EeLXXk0VwlxqTcFRfg9EhMW+17kbt9G0NrgCmhGb5vT2hyhJZLfDGx+7+5Uj/w==",
      "dev": true
    },
-    "yamljs": {
-      "version": "0.3.0",
-      "resolved": "https://registry.npmjs.org/yamljs/-/yamljs-0.3.0.tgz",
-      "integrity": "sha512-C/FsVVhht4iPQYXOInoxUM/1ELSf9EsgKH34FofQOp6hwCPrW4vG4w5++TED3xRUo8gD7l0P1J1dLlDYzODsTQ==",
-      "requires": {
-        "argparse": "^1.0.7",
-        "glob": "^7.0.5"
-      }
-    },
    "yargs": {
      "version": "13.3.0",
      "resolved": "https://registry.npmjs.org/yargs/-/yargs-13.3.0.tgz",
--- a/package.json
+++ b/package.json
@ -12,16 +12,17 @@
  "author": "",
  "license": "ISC",
  "dependencies": {
+    "@apidevtools/json-schema-ref-parser": "^8.0.0",
    "@types/mocha": "^5.2.7",
    "@types/node": "^13.1.6",
    "cfenv": "^1.2.2",
    "express": "^4.17.1",
+    "json-schema": "^0.2.5",
    "mongoose": "^5.8.7",
    "nodemon": "^2.0.3",
    "swagger-ui-express": "^4.1.2",
    "tslint": "^5.20.1",
-    "typescript": "^3.7.4",
-    "yamljs": "^0.3.0"
+    "typescript": "^3.7.4"
  },
  "devDependencies": {
    "mocha": "^7.0.0",
--- a/src/index.ts
+++ b/src/index.ts
@ -2,7 +2,7 @@ import cfenv from 'cfenv';
 import express from 'express';
 import mongoose from 'mongoose';
 import swagger from 'swagger-ui-express';
-import yaml from 'yamljs';
+import jsonRefParser, {JSONSchema} from '@apidevtools/json-schema-ref-parser';


 // tell if server is running in debug or production environment
@ -44,14 +44,14 @@ const port = process.env.PORT || 3000;
 app.use('/', require('./routes/root'));

 // Swagger UI
-app.use('/api', swagger.serve, swagger.setup(
-  yaml.load('./oas.yaml'),
-  {
-    defaultModelsExpandDepth: -1,
-    customCss: '.swagger-ui .topbar { display: none }'
-  }
-  )
-);
+let oasDoc: JSONSchema = {};
+jsonRefParser.bundle('oas/oas.yaml', (err, doc) => {
+  if(err) throw err;
+  oasDoc = doc;
+  oasDoc.paths = oasDoc.paths.allOf.reduce((s, e) => Object.assign(s, e));
+  swagger.setup(oasDoc, {defaultModelsExpandDepth: -1, customCss: '.swagger-ui .topbar { display: none }'});
+});
+app.use('/api', swagger.serve, swagger.setup(oasDoc, {defaultModelsExpandDepth: -1, customCss: '.swagger-ui .topbar { display: none }'}));

 // hook up server to port
 app.listen(port, () => {