docs: Add common API /secret to all Swagger filesi

close edgexfoundry#4649 Signed-off-by: Ginny Guan <[email protected]>
jinlinGuan · Aug 24, 2023 · f6c100a · f6c100a
1 parent 23e3a0f
commit f6c100a
Show file tree

Hide file tree

Showing 5 changed files with 350 additions and 6 deletions.
diff --git a/openapi/v3/core-command.yaml b/openapi/v3/core-command.yaml
@@ -321,6 +321,54 @@ components:
         serviceName:
           description: "Outputs the name of the service the response is from"
           type: string
+    BaseRequest:
+      description: "Defines basic properties which all use-case specific request DTO instances should support."
+      type: object
+      properties:
+        requestId:
+          description: "Uniquely identifies this request. For implementation, recommend this value be generated by the type's constructor."
+          type: string
+          format: uuid
+          example: "e6e8a2f4-eb14-4649-9e2b-175247911369"
+        apiVersion:
+          description: "A version number shows the API version in DTOs."
+          type: string
+          example: v3
+      required:
+        - apiVersion
+    SecretRequest:
+      allOf:
+        - $ref: '#/components/schemas/BaseRequest'
+      description: Defines the secret data to be stored
+      type: object
+      properties:
+        secretName:
+          description: Specifies the name of the secret
+          type: string
+          example: "credentials"
+        secretData:
+          description: A list of the key/value pairs of secret data to store
+          type: array
+          items:
+            $ref: '#/components/schemas/SecretDataKeyValue'
+      required:
+        - secretName
+        - secretData
+    SecretDataKeyValue:
+      description: Defines a key/value pair of secret data
+      type: object
+      properties:
+        key:
+          description: The key to identify the secret data
+          type: string
+          example: "secret-key"
+        value:
+          description: The value of the secret data
+          type: string
+          example: "secret-value"
+      required:
+        - key
+        - value          
   parameters:
     offsetParam:
       in: query
@@ -845,3 +893,52 @@ paths:
               examples:
                 500Example:
                   $ref: '#/components/examples/500Example'
+  /secret:
+    parameters:
+      - $ref: '#/components/parameters/correlatedRequestHeader'
+    post:
+      summary: Adds EdgeX Service exclusive secret to the Secret Store
+      requestBody:
+        content:
+          application/json:
+            schema:
+              allOf:
+                - $ref: '#/components/schemas/SecretRequest'
+        required: true
+      responses:
+        '201':
+          description: "Created"
+          headers:
+            X-Correlation-ID:
+              $ref: '#/components/headers/correlatedResponseHeader'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BaseResponse'
+              example:
+                apiVersion: "v3"
+                statusCode: 201
+        '400':
+          description: "Invalid request."
+          headers:
+            X-Correlation-ID:
+              $ref: '#/components/headers/correlatedResponseHeader'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                400Example:
+                  $ref: '#/components/examples/400Example'
+        '500':
+          description: "An unexpected error happened on the server."
+          headers:
+            X-Correlation-ID:
+              $ref: '#/components/headers/correlatedResponseHeader'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                500Example:
+                  $ref: '#/components/examples/500Example'
diff --git a/openapi/v3/core-data.yaml b/openapi/v3/core-data.yaml
@@ -302,6 +302,39 @@ components:
         serviceName:
           description: "Outputs the name of the service the response is from"
           type: string
+    SecretRequest:
+      allOf:
+        - $ref: '#/components/schemas/BaseRequest'
+      description: Defines the secret data to be stored
+      type: object
+      properties:
+        secretName:
+          description: Specifies the name of the secret
+          type: string
+          example: "credentials"
+        secretData:
+          description: A list of the key/value pairs of secret data to store
+          type: array
+          items:
+            $ref: '#/components/schemas/SecretDataKeyValue'
+      required:
+        - secretName
+        - secretData
+    SecretDataKeyValue:
+      description: Defines a key/value pair of secret data
+      type: object
+      properties:
+        key:
+          description: The key to identify the secret data
+          type: string
+          example: "secret-key"
+        value:
+          description: The value of the secret data
+          type: string
+          example: "secret-value"
+      required:
+        - key
+        - value 
   parameters:
     offsetParam:
       in: query
@@ -1930,4 +1963,53 @@ paths:
                 $ref: '#/components/schemas/ErrorResponse'
               examples:
                 500Example:
-                  $ref: '#/components/examples/500Example'
+                  $ref: '#/components/examples/500Example'
+  /secret:
+    parameters:
+      - $ref: '#/components/parameters/correlatedRequestHeader'
+    post:
+      summary: Adds EdgeX Service exclusive secret to the Secret Store
+      requestBody:
+        content:
+          application/json:
+            schema:
+              allOf:
+                - $ref: '#/components/schemas/SecretRequest'
+        required: true
+      responses:
+        '201':
+          description: "Created"
+          headers:
+            X-Correlation-ID:
+              $ref: '#/components/headers/correlatedResponseHeader'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BaseResponse'
+              example:
+                apiVersion: "v3"
+                statusCode: 201
+        '400':
+          description: "Invalid request."
+          headers:
+            X-Correlation-ID:
+              $ref: '#/components/headers/correlatedResponseHeader'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                400Example:
+                  $ref: '#/components/examples/400Example'
+        '500':
+          description: "An unexpected error happened on the server."
+          headers:
+            X-Correlation-ID:
+              $ref: '#/components/headers/correlatedResponseHeader'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                500Example:
+                  $ref: '#/components/examples/500Example'
diff --git a/openapi/v3/core-metadata.yaml b/openapi/v3/core-metadata.yaml
@@ -1060,6 +1060,39 @@ components:
       properties:
         uom:
           $ref: '#/components/schemas/UnitsOfMeasure'
+    SecretRequest:
+      allOf:
+        - $ref: '#/components/schemas/BaseRequest'
+      description: Defines the secret data to be stored
+      type: object
+      properties:
+        secretName:
+          description: Specifies the name of the secret
+          type: string
+          example: "credentials"
+        secretData:
+          description: A list of the key/value pairs of secret data to store
+          type: array
+          items:
+            $ref: '#/components/schemas/SecretDataKeyValue'
+      required:
+        - secretName
+        - secretData
+    SecretDataKeyValue:
+      description: Defines a key/value pair of secret data
+      type: object
+      properties:
+        key:
+          description: The key to identify the secret data
+          type: string
+          example: "secret-key"
+        value:
+          description: The value of the secret data
+          type: string
+          example: "secret-value"
+      required:
+        - key
+        - value 
   parameters:
     offsetParam:
       in: query
@@ -3998,3 +4031,52 @@ paths:
               examples:
                 500Example:
                   $ref: '#/components/examples/500Example'
+  /secret:
+    parameters:
+      - $ref: '#/components/parameters/correlatedRequestHeader'
+    post:
+      summary: Adds EdgeX Service exclusive secret to the Secret Store
+      requestBody:
+        content:
+          application/json:
+            schema:
+              allOf:
+                - $ref: '#/components/schemas/SecretRequest'
+        required: true
+      responses:
+        '201':
+          description: "Created"
+          headers:
+            X-Correlation-ID:
+              $ref: '#/components/headers/correlatedResponseHeader'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BaseResponse'
+              example:
+                apiVersion: "v3"
+                statusCode: 201
+        '400':
+          description: "Invalid request."
+          headers:
+            X-Correlation-ID:
+              $ref: '#/components/headers/correlatedResponseHeader'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                400Example:
+                  $ref: '#/components/examples/400Example'
+        '500':
+          description: "An unexpected error happened on the server."
+          headers:
+            X-Correlation-ID:
+              $ref: '#/components/headers/correlatedResponseHeader'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                500Example:
+                  $ref: '#/components/examples/500Example'
diff --git a/openapi/v3/support-notifications.yaml b/openapi/v3/support-notifications.yaml
@@ -540,29 +540,30 @@ components:
         secretName:
           description: Specifies the name of the secret
           type: string
+          example: "credentials"
         secretData:
           description: A list of the key/value pairs of secret data to store
           type: array
           items:
             $ref: '#/components/schemas/SecretDataKeyValue'
       required:
         - secretName
-        - secrets
+        - secretData
     SecretDataKeyValue:
       description: Defines a key/value pair of secret data
       type: object
       properties:
         key:
           description: The key to identify the secret data
           type: string
-          example: "appsecret"
+          example: "secret-key"
         value:
           description: The value of the secret data
           type: string
-          example: "appsecret-value"
+          example: "secret-value"
       required:
         - key
-        - value
+        - value 
   parameters:
     offsetParam:
       in: query