Finalise api docs

spec/components/parameters/fromDate.yaml

@@ -4,4 +4,4 @@ description: Start date of the query range in ISO format. Must be within 48 hour
 example: "2019-11-15T08:00:00Z"
 required: true
 schema:
-  type: ISO string
+  type: ISO string (UTC time)

spec/components/parameters/toDate.yaml

@@ -5,4 +5,4 @@ description: |
 example: "2019-11-16T08:00:00Z"
 required: true
 schema:
-  type: ISO string
+  type: ISO string (UTC time)

spec/components/schemas/objects/BatteryVoltage.yaml

@@ -0,0 +1,10 @@
+type: object
+properties:
+  messageId:
+    $ref: "#/components/schemas/messageId"
+  asset:
+    $ref: "#/components/schemas/asset"
+  recordedAt:
+    $ref: "#/components/schemas/recordedAt"
+  voltage:
+    $ref: "#/components/schemas/voltage"

spec/components/schemas/objects/BatteryVoltageArray.yaml

@@ -0,0 +1,3 @@
+type: array
+items:
+  $ref: "#/components/schemas/BatteryVoltage"

spec/components/schemas/objects/CombinedMileage.yaml

@@ -0,0 +1,6 @@
+type: object
+properties:
+  GPSMileage: 
+    $ref: "#/components/schemas/Mileage"
+  mileage:
+    $ref: "#/components/schemas/Mileage"

spec/components/schemas/objects/DTC.yaml

@@ -0,0 +1,10 @@
+type: object
+properties:
+  messageId:
+    $ref: "#/components/schemas/messageId"
+  asset:
+    $ref: "#/components/schemas/asset"
+  recordedAt:
+    $ref: "#/components/schemas/recordedAt"
+  rawData:
+    $ref: "#/components/schemas/rawData"

spec/components/schemas/objects/DTCArray.yaml

@@ -0,0 +1,3 @@
+type: array
+items:
+  $ref: "#/components/schemas/DTC"

spec/components/schemas/objects/Vin.yaml

@@ -0,0 +1,10 @@
+type: object
+properties:
+  messageId:
+    $ref: "#/components/schemas/messageId"
+  asset:
+    $ref: "#/components/schemas/asset"
+  recordedAt:
+    $ref: "#/components/schemas/recordedAt"
+  vin:
+    $ref: "#/components/schemas/vin"

spec/components/schemas/objects/VinArray.yaml

@@ -0,0 +1,3 @@
+type: array
+items:
+  $ref: "#/components/schemas/Vin"

spec/components/schemas/rawData.yaml

@@ -0,0 +1,3 @@
+type: string
+description: Raw DTC code information in stringified JSON format.
+example: [{\"mode\":3,\"ecu\":\"7E8\",\"dtc\":\"U11F5\"}]

spec/components/schemas/vin.yaml

@@ -0,0 +1,3 @@
+description: Vehicle Identification Number (VIN) of the car
+type: string
+example: WP0ZZZ99ZTS392124

spec/components/schemas/voltage.yaml

@@ -0,0 +1,3 @@
+type: double
+description: Battery voltage of the car's battery
+example: 12.09

spec/openapi.yaml

@@ -27,10 +27,37 @@ tags:
   - name: Fuel
     description: Get current and historical fuel information for an IMEI.
   - name: Mileage
-    description: Get current and historical mileage information for an IMEI.
+    description: Get current and historical mileage information for an IMEI. \
+      You will find two values here, the mileage reported by the vehicle (`Mileage`) and mileage calculated by the autoSense device (`GPS Mileage`)
   - name: PlugUnplug
     description: |
       Retrieve actual or historical information whether the MDI device is connected to the car's OBD port. \ 
       A new record is created each time the status of the devices changes from `plugged` or `unplugged`.
+  - name: Error Codes
+    description: |
+      Error codes reported by the vehicle and malfunction indicator light status (MIL).
 servers:
   - url: 'https://nebula.service.autosense.ch/api/v1'
+
+x-tagGroups:
+  - name: VIN
+    tags: 
+      - VIN
+  - name: Plug Unplug
+    tags:
+      - PlugUnplug
+  - name: Fuel
+    tags:
+      - Fuel
+  - name: Mileage
+    tags:
+      - Mileage
+      - GPS Mileage
+      - Combined Mileage
+  - name: Error Codes
+    tags:
+      - DTC
+      - MIL
+  - name: Battery Voltage
+    tags:
+      - Battery Voltage

spec/paths/asset@{assetId}@batteryVoltage.yaml

@@ -0,0 +1,28 @@
+parameters:
+  - $ref: "#/components/parameters/assetId"
+
+get:
+  tags:
+    - Battery Voltage
+  summary: Get Battery Voltage
+  description: |
+    Returns the latest recorded basttery voltage of the vehicle.
+  operationId: getBatteryVoltage
+  security:
+    - basicAuth: []
+  responses:
+    "200":
+      description: Success
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/BatteryVoltage"
+          example:
+            messageId: mdi-1313382935323227381
+            asset: "3516220738006655"
+            recordedAt": "2019-12-04T05:54:51Z"
+            voltage: 12.09
+    "401":
+      $ref: "#/components/responses/Unauthorized"
+    "404":
+      $ref: "#/components/responses/DataNotFound"

spec/paths/asset@{assetId}@batteryVoltage@history.yaml

@@ -0,0 +1,34 @@
+parameters:
+  - $ref: "#/components/parameters/assetId"
+  - $ref: "#/components/parameters/fromDate"
+  - $ref: "#/components/parameters/toDate"
+
+get:
+  tags:
+    - Battery Voltage
+  summary: Get Battery Voltage history
+  description: |
+    Returns an array of basttery voltage records for the car's battery.
+  operationId: getBatteryVoltageHistory
+  security:
+    - basicAuth: []
+  responses:
+    "200":
+      description: Success
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/BatteryVoltageArray"
+          example:
+            - messageId: mdi-1313382935323227381
+              asset: "3516220738006655"
+              recordedAt": "2019-12-04T05:54:51Z"
+              voltage: 12.09
+            - messageId: mdi-1313382935323227352
+              asset: "3516220738006655"
+              recordedAt": "2019-12-04T06:54:51Z"
+              voltage: 11.491
+    "401":
+      $ref: "#/components/responses/Unauthorized"
+    "404":
+      $ref: "#/components/responses/DataNotFound"

spec/paths/asset@{assetId}@combined-mileage.yaml

@@ -0,0 +1,35 @@
+parameters:
+  - $ref: "#/components/parameters/assetId"
+
+get:
+  tags:
+    - Combined Mileage
+  summary: Get combined mileage
+  description: |
+    Returns the latest recorded mileage information for a given IMEI.
+    This endpoint provides both the mileage reported by the vehicle and the mileage calculated by the onboard autoSense device GPS.
+  operationId: getCombinedMileage
+  security:
+    - basicAuth: []
+  responses:
+    "200":
+      description: Success
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/CombinedMileage"
+          example:
+            GPSMileage:
+              messageId: mdi-1313382935323227381
+              asset: "3516220738006655"
+              recordedAt": "2019-12-04T05:54:51Z"
+              mileage: 12500
+            mileage:
+              messageId: mdi-1313382935323227381
+              asset: "3516220738006655"
+              recordedAt": "2019-12-04T05:54:51Z"
+              mileage: 12500
+    "401":
+      $ref: "#/components/responses/Unauthorized"
+    "404":
+      $ref: "#/components/responses/DataNotFound"

spec/paths/asset@{assetId}@dtc.yaml

@@ -0,0 +1,28 @@
+parameters:
+  - $ref: "#/components/parameters/assetId"
+
+get:
+  tags:
+    - DTC
+  summary: Get DTC codes
+  description: |
+    Returns the latest recorded Diagnostics Trouble Codes (DTC) from the vehicle's onboard diagnostics system in a stringified JSON format.
+  operationId: getDtc
+  security:
+    - basicAuth: []
+  responses:
+    "200":
+      description: Success
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/DTC"
+          example:
+            messageId: mdi-1313382935323227381
+            asset: "3516220738006655"
+            recordedAt": "2019-12-04T05:54:51Z"
+            rawData: "[{\"mode\":3,\"ecu\":\"7E8\",\"dtc\":\"U11F5\"}]"
+    "401":
+      $ref: "#/components/responses/Unauthorized"
+    "404":
+      $ref: "#/components/responses/DataNotFound"

spec/paths/asset@{assetId}@dtc@history.yaml

@@ -0,0 +1,34 @@
+parameters:
+  - $ref: "#/components/parameters/assetId"
+  - $ref: "#/components/parameters/fromDate"
+  - $ref: "#/components/parameters/toDate"
+
+get:
+  tags:
+    - DTC
+  summary: Get DTC codes history
+  description: |
+    Returns an array of the recorded Diagnostics Trouble Codes (DTC) from the vehicle's onboard diagnostics system in a stringified JSON format.
+  operationId: getDtc
+  security:
+    - basicAuth: []
+  responses:
+    "200":
+      description: Success
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/DTCArray"
+          example:
+            - messageId: mdi-1313382935323227381
+              asset: "3516220738006655"
+              recordedAt": "2019-12-04T05:54:51Z"
+              rawData: "[{\"mode\":7,\"ecu\":\"7E8\",\"dtc\":\"U11F5\"}]"
+            - messageId: mdi-1313382935323227352
+              asset: "3516220738006655"
+              recordedAt": "2019-12-04T06:54:51Z"
+              rawData: "[{\"mode\":7,\"ecu\":\"7E8\",\"dtc\":\"U11F5\"}]"
+    "401":
+      $ref: "#/components/responses/Unauthorized"
+    "404":
+      $ref: "#/components/responses/DataNotFound"

spec/paths/asset@{assetId}@mil.yaml

@@ -0,0 +1,28 @@
+parameters:
+  - $ref: "#/components/parameters/assetId"
+
+get:
+  tags:
+    - MIL
+  summary: Get MIL codes
+  description: |
+    Returns the latest recorded Malfunction Indicator Light (MIL) codes from the vehicle's onboard diagnostics system in a stringified JSON format.
+  operationId: getMil
+  security:
+    - basicAuth: []
+  responses:
+    "200":
+      description: Success
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/DTC"
+          example:
+            messageId: mdi-1313382935323227381
+            asset: "3516220738006655"
+            recordedAt": "2019-12-04T05:54:51Z"
+            rawData: "[{\"mode\":3,\"ecu\":\"7E8\",\"dtc\":\"U11F5\"}]"
+    "401":
+      $ref: "#/components/responses/Unauthorized"
+    "404":
+      $ref: "#/components/responses/DataNotFound"

spec/paths/asset@{assetId}@mil@history.yaml

@@ -0,0 +1,34 @@
+parameters:
+  - $ref: "#/components/parameters/assetId"
+  - $ref: "#/components/parameters/fromDate"
+  - $ref: "#/components/parameters/toDate"
+
+get:
+  tags:
+    - MIL
+  summary: Get MIL codes history
+  description: |
+    Returns an array of the recorded Malfunction Indicator Light (MIL) codes from the vehicle's onboard diagnostics system in a stringified JSON format.
+  operationId: getMilHistory
+  security:
+    - basicAuth: []
+  responses:
+    "200":
+      description: Success
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/DTCArray"
+          example:
+            - messageId: mdi-1313382935323227381
+              asset: "3516220738006655"
+              recordedAt": "2019-12-04T05:54:51Z"
+              <??????>: "[{\"mode\":7,\"ecu\":\"7E8\",\"dtc\":\"U11F5\"}]"
+            - messageId: mdi-1313382935323227352
+              asset: "3516220738006655"
+              recordedAt": "2019-12-04T06:54:51Z"
+              <??????>: "[{\"mode\":7,\"ecu\":\"7E8\",\"dtc\":\"U11F5\"}]"
+    "401":
+      $ref: "#/components/responses/Unauthorized"
+    "404":
+      $ref: "#/components/responses/DataNotFound"

spec/paths/asset@{assetId}@mileage.yaml

@@ -7,6 +7,7 @@ get:
   summary: Get mileage
   description: |
     Returns the latest recorded mileage information for a given IMEI.
+    This endpoint refers to the mileage reported by the vehicle.
   operationId: getMileage
   security:
     - basicAuth: []

spec/paths/asset@{assetId}@obdmileage.yaml

@@ -0,0 +1,29 @@
+parameters:
+  - $ref: "#/components/parameters/assetId"
+
+get:
+  tags:
+    - GPS Mileage
+  summary: Get GPS mileage
+  description: |
+    Returns the latest recorded GPS mileage information for a given IMEI.
+    This endpoint refers to the mileage calculated by the device's GPS.
+  operationId: getGPSMileage
+  security:
+    - basicAuth: []
+  responses:
+    "200":
+      description: Success
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Mileage"
+          example:
+            messageId: mdi-1313382935323227381
+            asset: "3516220738006655"
+            recordedAt": "2019-12-04T05:54:51Z"
+            mileage: 11560
+    "401":
+      $ref: "#/components/responses/Unauthorized"
+    "404":
+      $ref: "#/components/responses/DataNotFound"