Clean up API spec structure and formatting

openapi.yaml

@@ -8,21 +8,40 @@ info:
     name: MIT
   version: 1.0.0
 servers:
-- url: http://milight-hub
+  - url: http://milight-hub
 tags:
-- name: system
-  description: Routes that return system information and allow you to control the device.
-- name: settings
-  description: Read and write settings
-- name: devices
-  description: Control lighting devices
-- name: transitions
-  description: Control transitions
+  - name: System
+    description: >
+      Routes that return system information and allow you to control the device.
+  - name: Settings
+    description: Read and write settings
+  - name: Device Control
+    description: Control lighting devices
+  - name: Device Control by Alias
+    description: Control lighting devices using aliases rather than raw IDs
+  - name: Raw Packet Handling
+    description: Read and write raw Milight packets
+  - name: Transitions
+    description: Control transitions
+x-tagGroups:
+  - name: Admin
+    tags:
+      - System
+      - Settings
+  - name: Devices
+    tags:
+      - Device Control
+      - Device Control by Alias
+      - Raw Packet Handling
+  - name: Transitions
+    tags:
+      - Transitions
+
 paths:
   /about:
     get:
       tags:
-      - system
+      - System
       summary: Get system information
       responses:
         200:
@@ -34,8 +53,8 @@ paths:
   /remote_configs:
     get:
       tags:
-        - system
-      summary: Returns list of supported remote types
+        - System
+      summary: List supported remote types
       responses:
         200:
           description: success
@@ -50,8 +69,8 @@ paths:
   /system:
     post:
       tags:
-      - system
-      summary: Control system
+      - System
+      summary: Send a system command
       description: >
         Send commands to the system.  Supported commands:
 
@@ -88,7 +107,7 @@ paths:
   /settings:
     get:
       tags:
-      - settings
+      - Settings
       summary: Get existing settings
       responses:
         200:
@@ -99,8 +118,8 @@ paths:
                 $ref: '#/components/schemas/Settings'
     put:
       tags:
-      - settings
-      summary: Patch existing settings with provided keys
+      - Settings
+      summary: Patch existing settings
       requestBody:
         content:
           application/json:
@@ -115,8 +134,8 @@ paths:
                 $ref: '#/components/schemas/BooleanResponse'
     post:
       tags:
-      - settings
-      summary: Overwrite existing settings with the provided file
+      - Settings
+      summary: Overwrite existing settings with a file
       requestBody:
         content:
           application/json:
@@ -133,10 +152,10 @@ paths:
   /gateway_traffic/{remote-type}:
     get:
       tags:
-      - devices
-      summary: Read a packet
+      - Raw Packet Handling
+      summary: Read a packet from a specific remote
       description:
-        Read a packet.  Does not return a response until a packet is read.
+        Read a packet from the given remote type.  Does not return a response until a packet is read.
         If `remote-type` is unspecified, will read from all remote types simultaneously.
       parameters:
         - $ref: '#/components/parameters/RemoteType'
@@ -146,10 +165,21 @@ paths:
           content:
             application/json:
               schema:
-                type: object
-                properties:
-                  packet_info:
-                    type: string
+                $ref: '#/components/schemas/ReadPacket'
+  /gateway_traffic:
+    get:
+      tags:
+      - Raw Packet Handling
+      summary: Read a packet from any remote
+      description:
+        Read a packet from any remote type.  Does not return a response until a packet is read.
+      responses:
+        200:
+          description: success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ReadPacket'
 
   /gateways/{device-id}/{remote-type}/{group-id}:
     parameters:
@@ -158,9 +188,12 @@ paths:
       - $ref: '#/components/parameters/GroupId'
     get:
       tags:
-        - devices
+        - Device Control
       summary:
         Get device state
+      description:
+        If `blockOnQueue` is provided, a response will not be returned until any unprocessed
+        packets in the command queue are finished sending.
       parameters:
         - $ref: '#/components/parameters/BlockOnQueue'
       responses:
@@ -172,9 +205,17 @@ paths:
                 $ref: '#/components/schemas/GroupState'
     put:
       tags:
-        - devices
+        - Device Control
       summary:
-        Patch device state with the specified keys
+        Patch device state
+      description:
+        Update state of the bulbs with the provided parameters.  Existing parameters will be
+        unchanged.
+
+        if `blockOnQueue` is set to true, the response will not return until packets corresponding
+        to the commands sent are processed, and the updated `GroupState` will be returned.  If
+        `blockOnQueue` is false or not provided, a simple response indicating success will be
+        returned.
       parameters:
         - $ref: '#/components/parameters/BlockOnQueue'
       requestBody:
@@ -192,16 +233,23 @@ paths:
               schema:
                 $ref: '#/components/schemas/BooleanResponse'
         200:
-          description: success
+          description: >
+            Success.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/GroupState'
+                oneOf:
+                  - $ref: '#/components/schemas/BooleanResponse'
+                  - $ref: '#/components/schemas/GroupState'
     delete:
       tags:
-        - devices
+        - Device Control
       summary:
-        Delete kept state for given device
+        Delete kept state
+      description:
+        Usets all known values for state fields for the corresponding device.  If MQTT is
+        configured, the retained state message corresponding to this device will also be
+        deleted.
       responses:
         200:
           description: success
@@ -214,8 +262,8 @@ paths:
       - $ref: '#/components/parameters/DeviceAlias'
     get:
       tags:
-        - devices
-      summary: Get state for the provided alias
+        - Device Control by Alias
+      summary: Get device state by alias
       responses:
         404:
           description: provided device alias does not exist
@@ -227,8 +275,8 @@ paths:
                 $ref: '#/components/schemas/GroupState'
     put:
       tags:
-        - devices
-      summary: Patch device state with the specified keys
+        - Device Control by Alias
+      summary: Patch device state by alias
       parameters:
         - $ref: '#/components/parameters/BlockOnQueue'
       requestBody:
@@ -253,8 +301,12 @@ paths:
                 $ref: '#/components/schemas/GroupState'
     delete:
       tags:
-        - devices
-      summary: Delete kept state for given device
+        - Device Control by Alias
+      summary: Delete kept state for alias
+      description:
+        Usets all known values for state fields for the corresponding device.  If MQTT is
+        configured, the retained state message corresponding to this device will also be
+        deleted.
       responses:
         200:
           description: success
@@ -268,7 +320,7 @@ paths:
       - $ref: '#/components/parameters/RemoteType'
     post:
       tags:
-        - devices
+        - Raw Packet Handling
       summary: Send a raw packet
       requestBody:
         content:
@@ -298,8 +350,8 @@ paths:
   /transitions:
     get:
       tags:
-        - transitions
-      summary: Get all active transitions
+        - Transitions
+      summary: List all active transitions
       responses:
         200:
           description: success
@@ -311,7 +363,7 @@ paths:
                   $ref: '#/components/schemas/TransitionData'
     post:
       tags:
-        - transitions
+        - Transitions
       summary: Create a new transition
       requestBody:
         content:
@@ -341,8 +393,8 @@ paths:
         required: true
     get:
       tags:
-        - transitions
-      summary: Get properties for provided transition ID
+        - Transitions
+      summary: Get properties for a transition
       responses:
         404:
           description: Provided transition ID not found
@@ -354,8 +406,8 @@ paths:
                 $ref: '#/components/schemas/TransitionData'
     delete:
       tags:
-        - transitions
-      summary: Delete provided transition
+        - Transitions
+      summary: Delete a transition
       responses:
         404:
           description: Provided transition ID not found
@@ -372,7 +424,7 @@ paths:
   /firmware:
     post:
       tags:
-        - system
+        - System
       summary:
         Update firmware
       requestBody:
@@ -546,6 +598,9 @@ components:
             bulb:
               $ref: '#/components/schemas/BulbId'
             type:
+              readOnly: true
+              description: >
+                Specifies whether this is a simple field transition, or a color transition.
               type: string
               enum:
                 - field
@@ -593,6 +648,7 @@ components:
             - temperature_up
     GroupState:
       type: object
+      description: Group state
       properties:
         state:
           $ref: '#/components/schemas/State'
@@ -630,6 +686,7 @@ components:
           oneOf:
             - type: string
               pattern: '[0-9]{1,3},[0-9]{1,3},[0-9]{1,3}'
+              example: '255,255,0'
             - type: object
               properties:
                 r:
@@ -638,6 +695,10 @@ components:
                   type: integer
                 b:
                   type: integer
+              example:
+                r: 255
+                g: 255
+                b: 0
           example:
             '255,0,255'
         level:
@@ -969,4 +1030,9 @@ components:
               description: Number of enqueued packets to be sent
             dropped_packets:
               type: integer
-              description: Number of packets that have been dropped since last reboot
+              description: Number of packets that have been dropped since last reboot
+    ReadPacket:
+      type: object
+      properties:
+        packet_info:
+          type: string