Merge pull request #477 from OpenEVSE/jeremypoulter/issue476

Fixes for errors in API docs

Author: jeremypoulter

.github/workflows/openapi_validate.yaml

@@ -0,0 +1,21 @@
+name: Validate API docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - master
+  pull_request:
+
+jobs:
+  build:
+    name: Run Spectral
+    runs-on: ubuntu-latest
+    steps:
+      # Check out the repository
+      - uses: actions/checkout@v3
+
+      # Run Spectral
+      - uses: stoplightio/spectral-action@latest
+        with:
+          file_glob: 'api.yml'

.stoplight/styleguide.json

@@ -7,6 +7,7 @@ info:
   contact:
     email: [email protected]
     name: Jeremy Poulter
+    url: https://github.com/jeremypoulter/
   license:
     name: Apache 2.0
     url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
@@ -79,34 +80,54 @@ paths:
       description: |
         The status endpoint can be called to post external data that should be updated by MQTT
         If MQTT is not an option, all external data needed can be updated from an HTTP POST request to /status endpoint.
-
-        Accepted parameters:
-        {
-          "voltage": int,          // live voltage in V
-          "shaper_live_pwr": int,  // total household live power in W
-          "solar": int,            // divert solar production in W
-          "grid_ie": int,          // divert grid -import/+export in W
-          "battery_level": int,    // vehicle soc in %
-          "battery_range": int,    // vehicle range
-          "time_to_full_charge": int    // vehicle charge ETA
-        }
-        
       responses:
-      '200':
+        '200':
           description: OK
           content:
             application/json:
               schema:
-                $ref: ./models/Status.yaml
+                type: object
+                properties:
+                  voltage:
+                    type: integer
+                    description: live voltage in V
+                  shaper_live_pwr:
+                    type: integer
+                    description: total household live power in W
+                  solar:
+                    type: integer
+                    description: divert solar production in W
+                  grid_ie:
+                    type: integer
+                    description: divert grid -import/+export in W
+                  battery_level:
+                    type: integer
+                    description: vehicle soc in %
+                  battery_range:
+                    type: integer
+                    description: vehicle range
+                  time_to_full_charge:
+                    type: integer
+                    description: vehicle charge ETA
+                x-examples:
+                  EVSE Status:
+                    voltage: 220
+                    shaper_live_pwr: 3400
+                    solar: 3000
+                    grid_ie: 3000
+                    battery_level: 85
+                    battery_range: 230
+                    time_to_full_charge: 1590
               examples:
                 EVSE Status:
-                  "voltage": 220
-                  "shaper_live_pwr": 3400
-                  "solar": 3000
-                  "grid_ie": 3000
-                  "battery_level": 85
-                  "battery_range": 230
-                  "time_to_full_charge" 1590
+                  value:
+                    voltage: 220
+                    shaper_live_pwr: 3400
+                    solar: 3000
+                    grid_ie: 3000
+                    battery_level: 85
+                    battery_range: 230
+                    time_to_full_charge: 1590
       tags:
         - Status
   /ws:
@@ -124,7 +145,7 @@ paths:
               schema:
                 $ref: ./models/Status.yaml
         '400':
-          descritpion: Error
+          description: Error
       tags:
         - Status
   /config:
@@ -456,7 +477,6 @@ paths:
                 properties:
                   current_day:
                     $ref: '#/components/schemas/Day'
-
       operationId: getSchedulePlan
       tags:
         - Schedule
@@ -578,6 +598,7 @@ components:
         - friday
         - saturday
         - sunday
+      x-examples: {}
     ScheduleEvent:
       type: object
       properties:

api.yml

@@ -84,85 +84,6 @@ x-examples:
     ocpp_energize_plug: true
     mqtt_protocol: mqtt
     charge_mode: fast
-examples:
-  - firmware: D7.1.2
-    protocol: '-'
-    espflash: 4194304
-    espinfo: ESP32r1 2 core WiFi BLE BT
-    buildenv: openevse_esp-wrover-kit
-    version: 4.1.0.dev
-    diode_check: true
-    gfci_check: true
-    ground_check: true
-    relay_check: true
-    vent_check: true
-    temp_check: true
-    service: 0
-    scale: 220
-    offset: 0
-    max_current_soft: 32
-    min_current_hard: 6
-    max_current_hard: 32
-    mqtt_supported_protocols:
-      - mqtt
-      - mqtts
-    http_supported_protocols:
-      - http
-      - https
-    ssid: wibble_ext
-    pass: _DUMMY_PASSWORD
-    www_username: ''
-    www_password: ''
-    hostname: openevse-a7d4
-    sntp_hostname: pool.ntp.org
-    time_zone: 'Europe/London|GMT0BST,M3.5.0/1,M10.5.0'
-    emoncms_server: 'https://emoncms.org'
-    emoncms_node: openevse-a7d4
-    emoncms_apikey: _DUMMY_PASSWORD
-    emoncms_fingerprint: ''
-    mqtt_server: homeassistant.lan
-    mqtt_port: 1883
-    mqtt_topic: openevse
-    mqtt_retained: false
-    mqtt_user: emonpi
-    mqtt_pass: _DUMMY_PASSWORD
-    mqtt_solar: ''
-    mqtt_grid_ie: emon/test/grid_ie
-    mqtt_vrms: emon/rightbar/voltage
-    mqtt_vehicle_soc: ''
-    mqtt_vehicle_range: ''
-    mqtt_vehicle_eta: ''
-    mqtt_announce_topic: openevse/announce/a7d4
-    ocpp_server: ''
-    ocpp_chargeBoxId: ''
-    ocpp_idTag: ''
-    tx_start_point: tx_pending
-    ohm: ''
-    divert_PV_ratio: 1.1
-    divert_attack_smoothing_factor: 0.4
-    divert_decay_smoothing_factor: 0.05
-    divert_min_charge_time: 10
-    tesla_access_token: _DUMMY_PASSWORD
-    tesla_refresh_token: _DUMMY_PASSWORD
-    tesla_created_at: 2479357952
-    tesla_expires_in: 3888000
-    tesla_vehicle_id: '142960157278'
-    led_brightness: 51
-    flags: 115467
-    emoncms_enabled: true
-    mqtt_enabled: true
-    mqtt_reject_unauthorized: true
-    ohm_enabled: false
-    sntp_enabled: true
-    tesla_enabled: true
-    divert_enabled: true
-    pause_uses_disabled: false
-    mqtt_vehicle_range_miles: false
-    ocpp_enabled: true
-    ocpp_suspend_evse: true
-    ocpp_energize_plug: true
-    mqtt_protocol: mqtt
-    charge_mode: fast
 x-tags:
   - Config
 properties:
@@ -367,7 +288,5 @@ properties:
   scheduler_start_window:
     type: number
     default: 600
-    description: >
-      The maximum number of seconds to randomly add/subtract from the a scheduled charge start time,
-      eg a value of 600 will adjust the start time my +/- 10 minutes. This is to help prevent large
-      syncrinised loads when multiple verchiles start charging at the same time.
+    description: |
+      The maximum number of seconds to randomly add/subtract from the a scheduled charge start time, eg a value of 600 will adjust the start time my +/- 10 minutes. This is to help prevent large syncrinised loads when multiple verchiles start charging at the same time.

models/Config.yaml

@@ -3,7 +3,6 @@ type: object
 x-tags:
   - Claims
 description: ''
-examples: []
 properties:
   state:
     $ref: ./EvseState.yaml