Merge pull request #187 from iamharisali/feature-master/IST-3550-config-api

IST-3350 Docs added for config API

Author: jleckie

openapi/components/parameters/configName.yaml

@@ -0,0 +1,7 @@
+name: configName
+in: path
+required: true
+description: The unique name/key of the configuration setting
+schema:
+  type: string
+example: site_name

openapi/components/requestBodies/config-bulk.yaml

@@ -0,0 +1,6 @@
+description: Bulk configuration update request
+required: true
+content:
+  application/json:
+    schema:
+      $ref: ../schemas/config-bulk-request.yaml

openapi/components/requestBodies/config-update.yaml

@@ -0,0 +1,6 @@
+description: Configuration update request
+required: true
+content:
+  application/json:
+    schema:
+      $ref: ../schemas/config-update.yaml

openapi/components/responses/config-bulk.yaml

@@ -0,0 +1,5 @@
+description: Bulk configuration update response
+content:
+  application/json:
+    schema:
+      $ref: ../schemas/config-bulk-response.yaml

openapi/components/responses/config-item.yaml

@@ -0,0 +1,5 @@
+description: Configuration item response
+content:
+  application/json:
+    schema:
+      $ref: ../schemas/config-item.yaml

openapi/components/schemas/config-bulk-request.yaml

@@ -0,0 +1,26 @@
+type: object
+required:
+  - configs
+properties:
+  configs:
+    type: array
+    description: Array of configuration updates to process
+    items:
+      type: object
+      required:
+        - name
+        - value
+      properties:
+        name:
+          type: string
+          description: The unique name/key of the configuration setting
+          example: "site_name"
+        value:
+          oneOf:
+            - type: string
+            - type: number
+            - type: boolean
+            - type: object
+            - type: array
+          description: The new configuration value
+          example: "Updated School Name"

openapi/components/schemas/config-bulk-response.yaml

@@ -0,0 +1,59 @@
+type: object
+required:
+  - results
+  - errors
+  - total_processed
+  - successful
+  - failed
+properties:
+  results:
+    type: array
+    description: Array of results for each config update attempt
+    items:
+      oneOf:
+        - allOf:
+            - $ref: ./config-item.yaml
+            - type: object
+              required:
+                - status
+              properties:
+                status:
+                  type: string
+                  enum: ["success"]
+                  example: "success"
+        - type: object
+          required:
+            - name
+            - status
+            - error
+          properties:
+            name:
+              type: string
+              description: The config name that failed to update
+              example: "invalid_config"
+            status:
+              type: string
+              enum: ["failed"]
+              example: "failed"
+            error:
+              type: string
+              description: Error message explaining why the update failed
+              example: "Config 'invalid_config' not found"
+  errors:
+    type: array
+    items:
+      type: string
+    description: Array of error messages for failed updates
+    example: ["Config 'invalid_config' not found"]
+  total_processed:
+    type: integer
+    description: Total number of config updates attempted
+    example: 5
+  successful:
+    type: integer
+    description: Number of config updates that succeeded
+    example: 4
+  failed:
+    type: integer
+    description: Number of config updates that failed
+    example: 1

openapi/components/schemas/config-item.yaml

@@ -0,0 +1,22 @@
+type: object
+required:
+  - name
+  - value
+properties:
+  name:
+    type: string
+    description: The unique name/key of the configuration setting
+    example: "site_name"
+  value:
+    oneOf:
+      - type: string
+      - type: number
+      - type: boolean
+      - type: object
+      - type: array
+    description: The configuration value. Can be any valid JSON type depending on the config setting.
+    example: "My School"
+  description:
+    type: string
+    description: Optional description of what this configuration setting controls
+    example: "The name of the school displayed in the header"

openapi/components/schemas/config-update.yaml

@@ -0,0 +1,13 @@
+type: object
+required:
+  - value
+properties:
+  value:
+    oneOf:
+      - type: string
+      - type: number
+      - type: boolean
+      - type: object
+      - type: array
+    description: The new configuration value. Can be any valid JSON type depending on the config setting.
+    example: "Updated School Name"

openapi/openapi.yaml

@@ -58,6 +58,11 @@ tags:
     description: |
       Create and manage calendar events.
 
+  - name: config
+    x-displayName: Configuration
+    description: |
+      Get and update system configuration values.
+
   - name: discussion
     x-displayName: Discussions
     description: |
@@ -297,6 +302,12 @@ paths:
   /api/search/folder/{id}:
     $ref: 'paths/api@search@folder@{id}.yaml'
 
+  /api/config:
+    $ref: 'paths/api@config.yaml'
+
+  /api/config/{configName}:
+    $ref: 'paths/api@config@{configName}.yaml'
+
   /group/getData/{id}:
     $ref: 'paths/group@getData@{id}.yaml'