feat(specs): add more descriptions to the Ingestion API (#1273)

Co-authored-by: Pierre Millot <[email protected]>

Author: shortcuts

specs/ingestion/common/authenticationParameters.yml

@@ -1,7 +1,7 @@
 type:
   name: type
   in: query
-  description: Which type the returned authentication should have. Can be a list of string separated with commas.
+  description: The type of the authentications to retrieve.
   required: false
   style: form
   explode: false
@@ -14,7 +14,7 @@ type:
 platform:
   name: platform
   in: query
-  description: Which platform the returned authentication should have. Can be a list of string separated with commas.
+  description: The platform of the authentications to retrieve.
   required: false
   style: form
   explode: false
@@ -24,7 +24,12 @@ platform:
       $ref: '#/platformWithNone'
     example: commercetools,none
 
+platformNone:
+  type: string
+  description: Used to filter Authentication without platform property.
+  enum: ['none']
+
 platformWithNone:
   oneOf:
     - $ref: './schemas/authentication.yml#/Platform'
-    - $ref: './schemas/authentication.yml#/PlatformNone'
+    - $ref: '#/platformNone'

specs/ingestion/common/destinationParameters.yml

@@ -1,7 +1,7 @@
 type:
   name: type
   in: query
-  description: Which type the returned destination should have. Can be a list of string separated with commas.
+  description: The type of the destinations to retrive.
   required: false
   style: form
   explode: false
@@ -14,11 +14,11 @@ type:
 authenticationID:
   name: authenticationID
   in: query
-  description: Which authenticationID the returned destination should have. Can be a list of string separated with commas.
+  description: The authenticationIDs of the destinations to retrive.
   required: false
   style: form
   explode: false
   schema:
     type: array
     items:
-      type: string
+      $ref: './schemas/common.yml#/authenticationID'

specs/ingestion/common/observabilityParameters.yml

@@ -30,4 +30,4 @@ taskID:
   in: query
   description: Filter by taskID.
   schema:
-    type: string
+    $ref: './schemas/common.yml#/taskID'

specs/ingestion/common/parameters.yml

@@ -1,56 +1,50 @@
-authenticationID:
+pathAuthenticationID:
   name: authenticationID
   in: path
-  description: The authentication uuid.
   required: true
+  description: The authentication UUID.
   schema:
-    type: string
-    example: 6c02aeb1-775e-418e-870b-1faccd4b2c0f
+    $ref: './schemas/common.yml#/authenticationID'
 
-destinationID:
+pathDestinationID:
   name: destinationID
   in: path
-  description: The destination uuid.
   required: true
+  description: The destination UUID.
   schema:
-    type: string
-    example: 6c02aeb1-775e-418e-870b-1faccd4b2c0f
+    $ref: './schemas/common.yml#/destinationID'
 
-sourceID:
+pathSourceID:
   name: sourceID
   in: path
-  description: The source uuid.
   required: true
+  description: The source UUID.
   schema:
-    type: string
-    example: 6c02aeb1-775e-418e-870b-1faccd4b2c0f
+    $ref: './schemas/common.yml#/sourceID'
 
-taskID:
+pathTaskID:
   name: taskID
   in: path
-  description: The task uuid.
   required: true
+  description: The task UUID.
   schema:
-    type: string
-    example: 6c02aeb1-775e-418e-870b-1faccd4b2c0f
+    $ref: './schemas/common.yml#/taskID'
 
-runID:
+pathRunID:
   name: runID
   in: path
-  description: The run uuid.
   required: true
+  description: The run UUID.
   schema:
-    type: string
-    example: 6c02aeb1-775e-418e-870b-1faccd4b2c0f
+    $ref: './schemas/common.yml#/runID'
 
-eventID:
+pathEventID:
   name: eventID
   in: path
-  description: The event uuid.
   required: true
+  description: The event UUID.
   schema:
-    type: string
-    example: 6c02aeb1-775e-418e-870b-1faccd4b2c0f
+    $ref: './schemas/common.yml#/eventID'
 
 itemsPerPage:
   name: itemsPerPage

specs/ingestion/common/schemas/authentication.yml

@@ -1,13 +1,14 @@
 Authentication:
   type: object
+  description: An authentication is used to login into a Source or a Destination.
   additionalProperties: false
   properties:
     authenticationID:
-      type: string
+      $ref: './common.yml#/authenticationID'
     type:
       $ref: '#/AuthenticationType'
     name:
-      type: string
+      $ref: './common.yml#/name'
     platform:
       $ref: '#/Platform'
     createdAt:
@@ -26,6 +27,7 @@ AuthenticationWithInput:
     - $ref: '#/Authentication'
     - type: object
       title: authenticationInput
+      description: The authentication input property stores the (encrypted) credentials.
       additionalProperties: false
       properties:
         input:
@@ -35,12 +37,13 @@ AuthenticationWithInput:
 
 AuthenticationCreate:
   type: object
+  description: The payload when creating an authentication.
   additionalProperties: false
   properties:
     type:
       $ref: '#/AuthenticationType'
     name:
-      type: string
+      $ref: './common.yml#/name'
     platform:
       $ref: '#/Platform'
     input:
@@ -52,12 +55,13 @@ AuthenticationCreate:
 
 AuthenticationCreateResponse:
   type: object
+  description: Response from the API when the Authentication is successfully created.
   additionalProperties: false
   properties:
     authenticationID:
-      type: string
+      $ref: './common.yml#/authenticationID'
     name:
-      type: string
+      $ref: './common.yml#/name'
     createdAt:
       $ref: './common.yml#/createdAt'
   required:
@@ -67,12 +71,13 @@ AuthenticationCreateResponse:
 
 AuthenticationUpdate:
   type: object
+  description: Payload to partialy update an Authentication.
   additionalProperties: false
   properties:
     type:
       $ref: '#/AuthenticationType'
     name:
-      type: string
+      $ref: './common.yml#/name'
     platform:
       $ref: '#/Platform'
     input:
@@ -81,11 +86,12 @@ AuthenticationUpdate:
 AuthenticationUpdateResponse:
   type: object
   additionalProperties: false
+  description: Response from the API when the Authentication is successfully updated.
   properties:
     authenticationID:
-      type: string
+      $ref: './common.yml#/authenticationID'
     name:
-      type: string
+      $ref: './common.yml#/name'
     updatedAt:
       $ref: './common.yml#/updatedAt'
   required:
@@ -96,40 +102,44 @@ AuthenticationUpdateResponse:
 AuthenticationSearch:
   type: object
   additionalProperties: false
+  description: Payload to search for multiple authentications, based on the given `authenticationIDs`.
   properties:
     authenticationIDs:
       type: array
       items:
-        type: string
+        $ref: './common.yml#/authenticationID'
   required:
     - authenticationIDs
 
 AuthenticationType:
   type: string
+  description: Type of the Authentication, defines what kind of object is stored in the input.
   enum: ['googleServiceAccount', 'basic', 'apiKey', 'oauth', 'algolia']
 
 Platform:
   type: string
+  description: Describe which platform the Authentication is used for.
   enum: ['bigcommerce', 'commercetools']
 
-PlatformNone:
-  type: string
-  enum: ['none']
-
 AuthGoogleServiceAccount:
   type: object
+  description: Authentication input to connect to a Google service (e.g. BigQuery).
   additionalProperties: false
   properties:
     clientEmail:
       type: string
+      description: Email address of the Service Account.
+      example: [email protected]
     privateKey:
       type: string
+      description: Private key of the Service Account.
   required:
     - clientEmail
     - privateKey
 
 AuthBasic:
   type: object
+  description: Authentication input for Basic login with username and password.
   additionalProperties: false
   properties:
     username:
@@ -142,6 +152,7 @@ AuthBasic:
 
 AuthAPIKey:
   type: object
+  description: Authentication input used for token credentials.
   additionalProperties: false
   properties:
     key:
@@ -151,16 +162,18 @@ AuthAPIKey:
 
 AuthOAuth:
   type: object
+  description: Authentication input for OAuth login.
   additionalProperties: false
   properties:
     url:
       type: string
+      description: The OAuth endpoint URL.
     client_id:
       type: string
+      description: The clientID.
     client_secret:
       type: string
-    scope:
-      type: string
+      description: The secret.
   required:
     - url
     - client_id
@@ -172,8 +185,10 @@ AuthAlgolia:
   properties:
     appID:
       type: string
+      description: Algolia Application ID.
     apiKey:
       type: string
+      description: Algolia API Key, with the correct rights to push to an index and change settings.
   required:
     - appID
     - apiKey

specs/ingestion/common/schemas/common.yml

@@ -26,3 +26,37 @@ DeleteResponse:
       description: Date of deletion (RFC3339 format).
   required:
     - deletedAt
+
+authenticationID:
+  type: string
+  description: The authentication UUID.
+  example: 6c02aeb1-775e-418e-870b-1faccd4b2c0f
+
+destinationID:
+  type: string
+  description: The destination UUID.
+  example: 6c02aeb1-775e-418e-870b-1faccd4b2c0f
+
+sourceID:
+  type: string
+  description: The source UUID.
+  example: 6c02aeb1-775e-418e-870b-1faccd4b2c0f
+
+taskID:
+  type: string
+  description: The task UUID.
+  example: 6c02aeb1-775e-418e-870b-1faccd4b2c0f
+
+runID:
+  type: string
+  description: The run UUID.
+  example: 6c02aeb1-775e-418e-870b-1faccd4b2c0f
+
+eventID:
+  type: string
+  description: The event UUID.
+  example: 6c02aeb1-775e-418e-870b-1faccd4b2c0f
+
+name:
+  type: string
+  description: An human readable name describing the object.