Merge pull request #93 from pat-git023/feat/userDefinedStates

feat: add userDefinedStates to OpenApi spec
BoschSmartHome · Dec 5, 2023 · 5c13bcc · 5c13bcc
2 parents 9090805 + d81491b
commit 5c13bcc
Show file tree

Hide file tree

Showing 4 changed files with 211 additions and 0 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [3.2.2] - 2023-12-03
+### Changed
+- New: UserDefinedStates
+
 ## [3.2.1] - 2023-02-09
 ### Changed
 - Added OpenAPI documentation

diff --git a/openapi/MainResources-local-openapi-v3.yml b/openapi/MainResources-local-openapi-v3.yml
@@ -23,6 +23,7 @@ tags:
   - name: Scenarios
   - name: Messages
   - name: Doors/Windows
+  - name: UserDefinedStates
 
 paths:
   ###
@@ -233,6 +234,101 @@ paths:
         '404':
           description: The entity could not be found.
 
+  ###
+  ### UserDefinedStates
+  ###
+  '/userdefinedstates':
+    get:
+      summary: List all available UserDefinedStates
+      description: Returns all UserDefinedStates
+      tags:
+      - UserDefinedStates
+      parameters: 
+      - $ref: '#/components/parameters/apiVersionHeaderParam'
+      responses:
+        '200':
+          description: Accepted request.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/UserDefinedState'
+  '/userdefinedstates/{userDefinedStateId}':
+    get:
+      summary: Retrieve a specific UserDefinedState.
+      description: |-
+          Returns the UserDefinedState identified by the `userDefinedStateId` path parameter. The
+          response includes details about the UserDefinedState.
+      tags:
+      - UserDefinedStates
+      parameters:
+      - $ref: '#/components/parameters/apiVersionHeaderParam'
+      - $ref: '#/components/parameters/userDefinedStateIdPathParam'
+      responses:
+        '200':
+          description: Accepted request.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserDefinedState'
+        '404':
+          description: |-
+            The entity could not be found. One of the defined path parameters was invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AdvancedError'
+  '/userdefinedstates/{userDefinedStateId}/state':
+    get:
+      summary: Retrieve the state of a specific UserDefinedState
+      description: |-
+        Retrieves the state of a UserDefinedState on the controller identified by the `userDefinedStateId` path parameter.
+      tags:
+        - UserDefinedStates
+      parameters:
+      - $ref: '#/components/parameters/apiVersionHeaderParam'
+      - $ref: '#/components/parameters/userDefinedStateIdPathParam'
+      responses:
+        '200':
+          description: Accepted request.
+          content:
+            text/plain:
+              schema:
+                type: string
+                example: true
+        '404':
+          description: The entity could not be found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AdvancedError'
+    put:
+      summary: Executes the state on the controller
+      description: |-
+        Executes the state on the controller identified by the `userDefinedStateId` path parameter.
+      tags:
+        - UserDefinedStates
+      parameters:
+      - $ref: '#/components/parameters/apiVersionHeaderParam'
+      - $ref: '#/components/parameters/userDefinedStateIdPathParam'
+      responses:
+        '200':
+          description: Accepted request.
+          content:
+            text/plain:
+              schema:
+                type: string
+                example: true
+        '404':
+          description: The entity could not be found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AdvancedError'
+        '405':
+          description: The method was not allowed.
+
 components:
   schemas:
     AdvancedError:
@@ -401,6 +497,23 @@ components:
           type: array
           items:
             type: object
+    UserDefinedState:
+      type: object
+      properties:
+        '@type':
+          type: string
+          description: The type of the Object.
+          example: userDefinedState
+        id:
+          type: string
+          description: "A single fully qualified identifier of the UserDefinedState."
+        name:
+          type: string
+          description: The name of the UserDefinedState.
+        state: 
+          type: boolean
+          description: The state of the UserDefinedState.
+          example: true
 
   parameters:
     apiVersionHeaderParam:
@@ -438,3 +551,10 @@ components:
       required: true
       schema:
         type: string
+    userDefinedStateIdPathParam:
+      name: userDefinedStateId
+      in: path
+      description: "A single fully qualified identifier."
+      required: true
+      schema:
+        type: string  
diff --git a/postman/Bosch Smart Home Controller.postman_collection.json b/postman/Bosch Smart Home Controller.postman_collection.json
@@ -596,6 +596,88 @@
 						}
 					},
 					"response": []
+				},
+				{
+					"name": "UserDefinedStates as array",
+					"request": {
+						"method": "GET",
+						"header": [],
+						"url": {
+							"raw": "{{shc_api}}/userdefinedstates",
+							"host": [
+								"{{shc_api}}"
+							],
+							"path": [
+								"userdefinedstates"
+							]
+						}
+					},
+					"response": []
+				},
+				{
+					"name": "UserDefinedState by Id",
+					"request": {
+						"method": "GET",
+						"header": [],
+						"url": {
+							"raw": "{{shc_api}}/userdefinedstates/{{user_defined_state_id}}",
+							"host": [
+								"{{shc_api}}"
+							],
+							"path": [
+								"userdefinedstates",
+								"{{user_defined_state_id}}"
+							]
+						}
+					},
+					"response": []
+				},
+				{
+					"name": "State of UserDefinedState by Id",
+					"request": {
+						"method": "GET",
+						"header": [],
+						"url": {
+							"raw": "{{shc_api}}/userdefinedstates/{{user_defined_state_id}}/state",
+							"host": [
+								"{{shc_api}}"
+							],
+							"path": [
+								"userdefinedstates",
+								"{{user_defined_state_id}}",
+								"state"
+							]
+						}
+					},
+					"response": []
+				},
+				{
+					"name": "UserDefinedState",
+					"request": {
+						"method": "PUT",
+						"header": [],
+						"body": {
+							"mode": "raw",
+							"raw": "true",
+							"options": {
+								"raw": {
+									"language": "json"
+								}
+							}
+						},
+						"url": {
+							"raw": "{{shc_api}}/userdefinedstates/{{user_defined_state_id}}/state",
+							"host": [
+								"{{shc_api}}"
+							],
+							"path": [
+								"userdefinedstates",
+								"{{user_defined_state_id}}",
+								"state"
+							]
+						}
+					},
+					"response": []
 				}
 			]
 		},

diff --git a/postman/Bosch Smart Home Controller.postman_environment.json b/postman/Bosch Smart Home Controller.postman_environment.json
@@ -67,6 +67,11 @@
 			"value": "",
 			"type": "any",
 			"enabled": true
+		},
+		{
+			"key": "user_defined_state_id",
+			"value": "",
+			"enabled": true
 		}
 	],
 	"_postman_variable_scope": "environment",