route openapi specs

docs/openapi.yaml

@@ -0,0 +1,166 @@
+openapi: "3.0.0"
+info:
+    title: PyHeatpump API specifications
+    version: 0.1.0
+paths:
+    /:
+        get:
+            operation: get_specs
+            summary: List API specs (read this file)
+            responses:
+                '200':
+                    description: 200 response
+                    content:
+                        application/json:
+                            examples:
+                                value:
+                                    [route1, route2, ..., routeN]
+    /config:
+        get:
+            operation: get_config
+            summary: Retrieves current configuration values
+            responses:
+                '200':
+                    description: The dictionary of configuration
+                    content:
+                        application/json:
+                            examples:
+                                configuration:
+                                    heatpump:
+                                        option: value
+                                    supervisor:
+                                        option: value
+                '500':
+                    description: Failed to get configuration
+
+
+        post:
+            operation: set_config
+            summary: Sets the configuration values
+            content:
+                application/json:
+                    examples:
+                        valuesToSet:
+                            heatpump:
+                                database: memory
+                            supervisor:
+                                scheme: https
+                                host: supervision.gteo.fr:8081
+
+                text/plain:
+                    examples:
+                        valuesToSet: heatpump.serial_port=/dev/serial0
+
+
+            responses:
+                '200':
+                    description: Setting configuration succeeded
+                '403':
+                    description: Setting configuration forbidden
+                '404':
+                    description: Specified setting does not exists
+                '415':
+                    description: Sent data cannot be treated
+
+    /variable_types:
+        get:
+            operation: get_variable_types
+            summary: Retrieves the list of variable types and their parameters
+            responses:
+                '200':
+                    description: The variable types details, as described in the database tab var_types
+                    content:
+                        application/json:
+                            examples:
+                                variableTypes:
+                                    analog:
+                                        slabel: A
+                                        type: float
+                                        start_address: 0
+                                        end_address: 250
+                                    integer:
+                                        slabel: I
+                                        type: int
+                                        start_address: 0
+                                        end_address: 250
+                                    digital:
+                                        slabel: D
+                                        type: boolean
+                                        start_address: 0
+                                        end_address: 250
+        set:
+            operation: set_variable_types
+            summary: Retrieves the list of variable types and their parameters
+            content:
+                application/json:
+                    examples:
+                        variableTypes:
+                            analog:
+                                slabel: A
+                                type: float
+                                start_address: 0
+                                end_address: 250
+                            integer:
+                                slabel: I
+                                type: int
+                                start_address: 0
+                                end_address: 250
+                            digital:
+                                slabel: D
+                                type: boolean
+                                start_address: 0
+                                end_address: 250
+             responses:
+                '200':
+                    description: The variable types details were correctly set.
+
+
+    /variables:
+        get:
+            operation: get_variables
+            summary: Retrieves a list of variables, by type
+            parameters:
+                changed:
+                    description: List only variables where values changed since last fetch
+                errored:
+                    description: Listen only variables that the program was unable to fetch
+            responses:
+                '200':
+                    application/json:
+                        description: List of the variables
+                        examples:
+                            variablesList:
+                                A:
+                                    - 42: 34
+                                    - 24: 43
+                                I:
+                                    - 4200: 777
+
+        post:
+            operation: set_variables
+            summary: Make changes to some variables
+            content:
+                application/json:
+                    description: List of the changes to make
+                    examples:
+                        variablesToSet:
+                            A:
+                                42: 34
+                                24: 43
+                            I:
+                                4200: 777
+                            D:
+                                100: 1
+                                200: 0
+            responses:
+                '500':
+                    description: Some variables cannot be set
+                    content:
+                        examples:
+                            variablesErrored:
+                                A:
+                                    - 42
+                                    - 24
+                                I:
+                                    - 4200
+                                    - 420