fix(spec): finish tags (#483)

netlify.toml

@@ -1,7 +1,7 @@
 [build]
   command="BUNDLE_WITH_DOC=true DOCKER=true yarn cli build specs all && yarn website:build"
   publish="website/build"
-  ignore="git diff --quiet $COMMIT_REF $CACHED_COMMIT_REF -- website/"
+  ignore="git diff --quiet $COMMIT_REF $CACHED_COMMIT_REF -- website/ specs/"
 
 [build.environment]
   YARN_VERSION = "3.1.1"

specs/personalization/paths/deleteUserProfile.yml

@@ -1,7 +1,14 @@
 delete:
+  tags:
+    - profiles
   operationId: deleteUserProfile
-  description: Returns, as part of the response, a date until which the data can safely be considered as deleted for the given user. This means that if you send events for the given user before this date, they will be ignored. Any data received after the deletedUntil date will start building a new user profile. It might take a couple hours before for the deletion request to be fully processed.
-  summary: Delete the user profile and all its associated data.
+  summary: Delete a user profile.
+  description: |
+    Delete the user profile and all its associated data.
+
+    Returns, as part of the response, a date until which the data can safely be considered as deleted for the given user. This means if you send events for the given user before this date, they will be ignored. Any data received after the deletedUntil date will start building a new user profile.
+
+    It might take a couple hours for the deletion request to be fully processed.
   parameters:
     - $ref: '../common/parameters.yml#/UserToken'
   responses:
@@ -21,7 +28,7 @@ delete:
                 $ref: '../common/parameters.yml#/userToken'
               deletedUntil:
                 type: string
-                description: A date until which the data can safely be considered as deleted for the given user. Any data received after the deletedUntil date will start building a new user profile.
+                description: A date until which the data can safely be considered as deleted for the given user. Any data received after the `deletedUntil` date will start building a new user profile.
     '400':
       $ref: '../../common/responses/BadRequest.yml'
     '402':

specs/personalization/paths/getUserTokenProfile.yml

@@ -1,7 +1,12 @@
 get:
+  tags:
+    - profiles
   operationId: getUserTokenProfile
-  description: The profile is structured by facet name used in the strategy. Each facet value is mapped to its score. Each score represents the user affinity for a specific facet value given the userToken past events and the Personalization strategy defined. Scores are bounded to 20. The last processed event timestamp is provided using the ISO 8601 format for debugging purposes.
-  summary: Get the user profile built from Personalization strategy.
+  summary: Get a user profile.
+  description: |
+    Get the user profile built from Personalization strategy.
+
+    The profile is structured by facet name used in the strategy. Each facet value is mapped to its score. Each score represents the user affinity for a specific facet value given the userToken past events and the Personalization strategy defined. Scores are bounded to 20. The last processed event timestamp is provided using the ISO 8601 format for debugging purposes.
   parameters:
     - $ref: '../common/parameters.yml#/UserToken'
   responses:

specs/personalization/paths/personalizationStrategy.yml

@@ -1,7 +1,31 @@
+get:
+  tags:
+    - strategies
+  operationId: getPersonalizationStrategy
+  summary: Get the current strategy.
+  description: The strategy contains information on the events and facets that impact user profiles and personalized search results.
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: '../common/schemas/personalizationStrategy.yml#/personalizationStrategyParams'
+    '400':
+      $ref: '../../common/responses/BadRequest.yml'
+    '402':
+      $ref: '../../common/responses/FeatureNotEnabled.yml'
+    '403':
+      $ref: '../../common/responses/MethodNotAllowed.yml'
+    '404':
+      $ref: '../../common/responses/IndexNotFound.yml'
+
 post:
+  tags:
+    - strategies
   operationId: setPersonalizationStrategy
+  summary: Set a new strategy.
   description: A strategy defines the events and facets that impact user profiles and personalized search results.
-  summary: Set a new personalization strategy.
   requestBody:
     required: true
     content:
@@ -31,22 +55,3 @@ post:
       $ref: '../../common/responses/MethodNotAllowed.yml'
     '404':
       $ref: '../../common/responses/IndexNotFound.yml'
-get:
-  operationId: getPersonalizationStrategy
-  description: The strategy contains information on the events and facets that impact user profiles and personalized search results.
-  summary: Get the current personalization strategy.
-  responses:
-    '200':
-      description: OK
-      content:
-        application/json:
-          schema:
-            $ref: '../common/schemas/personalizationStrategy.yml#/personalizationStrategyParams'
-    '400':
-      $ref: '../../common/responses/BadRequest.yml'
-    '402':
-      $ref: '../../common/responses/FeatureNotEnabled.yml'
-    '403':
-      $ref: '../../common/responses/MethodNotAllowed.yml'
-    '404':
-      $ref: '../../common/responses/IndexNotFound.yml'

specs/personalization/spec.yml

@@ -20,6 +20,18 @@ servers:
 security:
   - appId: []
     apiKey: []
+tags:
+  - name: profiles
+    x-displayName: Profiles
+    description: Manage users' profiles.
+  - name: strategies
+    x-displayName: Strategies
+    description: Manage personalization strategies.
+x-tagGroups:
+  - name: General
+    tags:
+      - profiles
+      - strategies
 paths:
   # ######################
   # ### Custom request ###

specs/predict/paths/fetchUserProfile.yml

@@ -1,4 +1,6 @@
 post:
+  tags:
+    - profiles
   operationId: fetchUserProfile
   description: Get predictions, properties (raw, computed or custom) and segments (computed or custom) for a user profile.
   summary: Get user profile.

specs/predict/spec.yml

@@ -20,6 +20,14 @@ servers:
 security:
   - appId: []
     apiKey: []
+tags:
+  - name: profiles
+    x-displayName: Profiles
+    description: Manage users' profiles.
+x-tagGroups:
+  - name: General
+    tags:
+      - profiles
 paths:
   # ######################
   # ### Custom request ###

specs/query-suggestions/paths/getConfigurationStatus.yml

@@ -1,10 +1,12 @@
 get:
+  tags:
+    - configurations
   operationId: getConfigStatus
+  summary: Get configuration status.
   description: >
     Get the status of a Query Suggestion's index.
 
     The status includes whether the Query Suggestions index is currently in the process of being built, and the last build time.
-  summary: Get the status of a Query Suggestion's index.
   parameters:
     - $ref: '../../common/parameters.yml#/IndexName'
   responses:

specs/query-suggestions/paths/getLogFile.yml

@@ -1,7 +1,9 @@
 get:
+  tags:
+    - advanced
   operationId: getLogFile
+  summary: Get a log file.
   description: Get the log file of the last build of a single Query Suggestion index.
-  summary: Get the log file of the last build of a single Query Suggestion index.
   parameters:
     - $ref: '../../common/parameters.yml#/IndexName'
   responses:

specs/query-suggestions/paths/qsConfig.yml

@@ -1,7 +1,35 @@
+get:
+  tags:
+    - configurations
+  operationId: getConfig
+  summary: Get a single configuration.
+  description: Get the configuration of a single Query Suggestions index.
+  parameters:
+    - $ref: '../../common/parameters.yml#/IndexName'
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: '../common/schemas/QuerySuggestionsIndex.yml#/QuerySuggestionsIndex'
+    '400':
+      $ref: '../../common/responses/BadRequest.yml'
+    '401':
+      $ref: '../../common/responses/Unauthorized.yml'
+    '403':
+      $ref: '../../common/responses/MethodNotAllowed.yml'
+    '404':
+      $ref: '../../common/responses/IndexNotFound.yml'
+    '500':
+      $ref: '../../common/responses/InternalError.yml'
+
 put:
+  tags:
+    - configurations
   operationId: updateConfig
+  summary: Update a configuration.
   description: Update the configuration of a Query Suggestions index.
-  summary: Update the configuration of a Query Suggestions index.
   parameters:
     - $ref: '../../common/parameters.yml#/IndexName'
   requestBody:
@@ -19,14 +47,16 @@ put:
       $ref: '../../common/responses/InternalError.yml'
 
 delete:
+  tags:
+    - configurations
   operationId: deleteConfig
+  summary: Delete a configuration.
   description: >
     Delete a configuration of a Query Suggestion's index.
 
     By deleting a configuraton, you stop all updates to the underlying query suggestion index.
 
     Note that when doing this, the underlying index does not change - existing suggestions remain untouched.
-  summary: Delete a configuration of a Query Suggestion's index.
   parameters:
     - $ref: '../../common/parameters.yml#/IndexName'
   responses:
@@ -38,27 +68,3 @@ delete:
       $ref: '../../common/responses/MethodNotAllowed.yml'
     '500':
       $ref: '../../common/responses/InternalError.yml'
-
-get:
-  operationId: getConfig
-  description: Get the configuration of a single Query Suggestions index.
-  summary: Get the configuration of a single Query Suggestions index.
-  parameters:
-    - $ref: '../../common/parameters.yml#/IndexName'
-  responses:
-    '200':
-      description: OK
-      content:
-        application/json:
-          schema:
-            $ref: '../common/schemas/QuerySuggestionsIndex.yml#/QuerySuggestionsIndex'
-    '400':
-      $ref: '../../common/responses/BadRequest.yml'
-    '401':
-      $ref: '../../common/responses/Unauthorized.yml'
-    '403':
-      $ref: '../../common/responses/MethodNotAllowed.yml'
-    '404':
-      $ref: '../../common/responses/IndexNotFound.yml'
-    '500':
-      $ref: '../../common/responses/InternalError.yml'

specs/query-suggestions/paths/qsConfigs.yml

@@ -1,34 +1,12 @@
-post:
-  operationId: createConfig
-  description: Create a configuration of a Query Suggestions index. There's a limit of 100 configurations per application.
-  summary: Create a configuration of a Query Suggestions index.
-  requestBody:
-    required: true
-    content:
-      application/json:
-        schema:
-          $ref: '../common/parameters.yml#/QuerySuggestionsIndexWithIndexParam'
-  responses:
-    '200':
-      $ref: '../../common/responses/Success.yml'
-    '400':
-      $ref: '../../common/responses/BadRequest.yml'
-    '401':
-      $ref: '../../common/responses/Unauthorized.yml'
-    '403':
-      $ref: '../../common/responses/MethodNotAllowed.yml'
-    '422':
-      $ref: '../../common/responses/StatusUnprocessableEntity.yml'
-    '500':
-      $ref: '../../common/responses/InternalError.yml'
-
 get:
+  tags:
+    - configurations
   operationId: getAllConfigs
+  summary: List configurations.
   description: >
     Get all the configurations of Query Suggestions.
 
     For each index, you get a block of JSON with a list of its configuration settings.
-  summary: Get all the configurations of Query Suggestions.
   responses:
     '200':
       description: OK
@@ -46,3 +24,29 @@ get:
       $ref: '../../common/responses/StatusUnprocessableEntity.yml'
     '500':
       $ref: '../../common/responses/InternalError.yml'
+
+post:
+  tags:
+    - configurations
+  operationId: createConfig
+  summary: Create a configuration.
+  description: Create a configuration of a Query Suggestions index. There's a limit of 100 configurations per application.
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '../common/parameters.yml#/QuerySuggestionsIndexWithIndexParam'
+  responses:
+    '200':
+      $ref: '../../common/responses/Success.yml'
+    '400':
+      $ref: '../../common/responses/BadRequest.yml'
+    '401':
+      $ref: '../../common/responses/Unauthorized.yml'
+    '403':
+      $ref: '../../common/responses/MethodNotAllowed.yml'
+    '422':
+      $ref: '../../common/responses/StatusUnprocessableEntity.yml'
+    '500':
+      $ref: '../../common/responses/InternalError.yml'

specs/query-suggestions/spec.yml

@@ -20,6 +20,20 @@ servers:
 security:
   - appId: []
     apiKey: []
+tags:
+  - name: advanced
+    x-displayName: Advanced
+    description: Advanced operations.
+  - name: configurations
+    x-displayName: Configurations
+    description: Manage Query Suggestions configurations.
+x-tagGroups:
+  - name: General
+    tags:
+      - configurations
+  - name: Others
+    tags:
+      - advanced
 paths:
   # ######################
   # ### Custom request ###

specs/recommend/paths/getRecommendations.yml

@@ -1,7 +1,9 @@
 post:
+  tags:
+    - recommendations
   operationId: getRecommendations
-  description: Returns recommendations for a specific model and objectID.
-  summary: Returns recommendations for a specific model and objectID.
+  summary: Get results.
+  description: Returns recommendations or trending results, for a specific model and `objectID`.
   requestBody:
     required: true
     content:

specs/recommend/spec.yml

@@ -33,6 +33,14 @@ servers:
 security:
   - appId: []
     apiKey: []
+tags:
+  - name: recommendations
+    x-displayName: Recommendations & Trending
+    description: Manage recommendations.
+x-tagGroups:
+  - name: General
+    tags:
+      - recommendations
 paths:
   # ######################
   # ### Custom request ###

specs/sources/paths/ingest/postUrl.yml

@@ -1,6 +1,8 @@
 post:
+  tags:
+    - jobs
   operationId: postIngestUrl
-  summary: Create a new ingestion job via URL.
+  summary: Create fetch URL job.
   description: Add an ingestion job that will fetch data from an URL.
   requestBody:
     required: true

specs/sources/spec.yml

@@ -20,6 +20,14 @@ servers:
 security:
   - appId: []
     apiKey: []
+tags:
+  - name: jobs
+    x-displayName: Jobs
+    description: Manage jobs.
+x-tagGroups:
+  - name: General
+    tags:
+      - jobs
 paths:
   # ######################
   # ### Custom request ###