fix(spec): add more tags (#464)

Co-authored-by: Clément Vannicatte <[email protected]>

Author: Samuel Bodin

specs/abtesting/paths/abtest.yml

@@ -1,10 +1,10 @@
 get:
+  tags:
+    - abtest
   operationId: getABTest
+  summary: Get a test.
   description: >
-    Returns metadata and metrics for A/B test id.
-
-    Behaves in the same way as GET /2/abtests however the endpoint will return 403.
-  summary: Returns metadata and metrics for A/B test id.
+    Returns metadata and metrics for an A/B test.
   parameters:
     - $ref: '../common/parameters.yml#/ID'
   responses:
@@ -24,9 +24,11 @@ get:
       $ref: '../../common/responses/IndexNotFound.yml'
 
 delete:
+  tags:
+    - abtest
   operationId: deleteABTest
-  description: Deletes the A/B Test and removes all associated metadata & metrics.
-  summary: Deletes the A/B Test.
+  summary: Delete a test.
+  description: Delete a test.
   parameters:
     - $ref: '../common/parameters.yml#/ID'
   responses:

specs/abtesting/paths/abtests.yml

@@ -1,10 +1,12 @@
 post:
+  tags:
+    - abtest
   operationId: addABTests
+  summary: Create a test.
   description: >
     Creates a new A/B test with provided configuration.
 
     You can set an A/B test on two different indices with different settings, or on the same index with different search parameters by providing a customSearchParameters setting on one of the variants.
-  summary: Creates a new A/B test with provided configuration.
   requestBody:
     required: true
     content:
@@ -46,10 +48,14 @@ post:
       $ref: '../../common/responses/IndexNotFound.yml'
 
 get:
+  tags:
+    - abtest
   operationId: listABTests
+  summary: List all tests.
   description: >
-    Fetch all existing A/B tests for App that are available for the current API Key. Returns an array of metadata and metrics. When no data has been processed, the metrics will be returned as null.
-  summary: Fetch all existing A/B tests for App that are available for the current API Key.
+    Fetch all existing A/B tests for App that are available for the current API Key.
+
+    When no data has been processed, the metrics will be returned as null.
   parameters:
     - $ref: '../../common/parameters.yml#/Offset'
     - $ref: '../../common/parameters.yml#/Limit'

specs/abtesting/paths/stopABTest.yml

@@ -1,12 +1,14 @@
 post:
+  tags:
+    - abtest
   operationId: stopABTest
+  summary: Stop a test.
   description: >
     Marks the A/B test as stopped.
 
     At this point, the test is over and cannot be restarted.
     As a result, your application is back to normal: index A will perform as usual, receiving 100% of all search requests.
     Associated metadata and metrics are still stored.
-  summary: Marks the A/B test as stopped.
   parameters:
     - $ref: '../common/parameters.yml#/ID'
   responses:

specs/abtesting/spec.yml

@@ -21,6 +21,14 @@ servers:
 security:
   - appId: []
     apiKey: []
+tags:
+  - name: abtest
+    x-displayName: A/B Testing
+    description: Manage A/B Tests.
+x-tagGroups:
+  - name: General
+    tags:
+      - abtest
 paths:
   # ######################
   # ### Custom request ###

specs/analytics/paths/click/getAverageClickPosition.yml

@@ -1,7 +1,9 @@
 get:
+  tags:
+    - click
   operationId: getAverageClickPosition
+  summary: Get average click position.
   description: Returns the average click position. The endpoint returns a value for the complete given time range, as well as a value per day.
-  summary: Returns the average click position.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../../common/parameters.yml#/StartDate'

specs/analytics/paths/click/getClickPositions.yml

@@ -1,7 +1,13 @@
 get:
+  tags:
+    - click
   operationId: getClickPositions
-  description: Returns the distribution of clicks per range of positions.
-  summary: Returns the distribution of clicks per range of positions.
+  summary: Get clicks per positions.
+  description: |
+    Returns the distribution of clicks per range of positions.
+
+    If the groups all have a count of 0, it means Algolia didn’t receive any click events for the queries with the clickAnalytics search parameter set to true.
+    The count is 0 until Algolia receives at least one click event.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../../common/parameters.yml#/StartDate'
@@ -35,9 +41,11 @@ get:
                       description: >
                         Range of positions with the following pattern:
 
-                        Positions from 1 to 10 included are displayed in separated groups.
-                        Positions from 11 to 20 included are grouped together.
-                        Positions from 21 and up are grouped together.
+                        - Positions from 1 to 10 included are displayed in separated groups.
+
+                        - Positions from 11 to 20 included are grouped together.
+
+                        - Positions from 21 and up are grouped together.
                       type: array
                       items:
                         type: integer

specs/analytics/paths/click/getClickThroughRate.yml

@@ -1,7 +1,9 @@
 get:
+  tags:
+    - click
   operationId: getClickThroughRate
+  summary: Get click-through rate (CTR).
   description: Returns a click-through rate (CTR). The endpoint returns a value for the complete given time range, as well as a value per day. It also returns the count of clicks and searches used to compute the rates.
-  summary: Returns a click-through rate (CTR).
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../../common/parameters.yml#/StartDate'

specs/analytics/paths/click/getConversionRate.yml

@@ -1,7 +1,9 @@
 get:
+  tags:
+    - click
   operationId: getConversationRate
+  summary: Get conversion rate (CR).
   description: Returns a conversion rate (CR). The endpoint returns a value for the complete given time range, as well as a value per day. It also returns the count of conversion and searches used to compute the rates.
-  summary: Returns a conversion rate (CR).
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../../common/parameters.yml#/StartDate'

specs/analytics/paths/search/getNoClickRate.yml

@@ -1,7 +1,9 @@
 get:
+  tags:
+    - search
   operationId: getNoClickRate
+  summary: Get no click rate.
   description: Returns the rate at which searches didn't lead to any clicks. The endpoint returns a value for the complete given time range, as well as a value per day. It also returns the count of searches and searches without clicks.
-  summary: Returns the rate at which searches didn't lead to any clicks.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../../common/parameters.yml#/StartDate'

specs/analytics/paths/search/getNoResultsRate.yml

@@ -1,7 +1,9 @@
 get:
+  tags:
+    - search
   operationId: getNoResultsRate
+  summary: Get no results rate.
   description: Returns the rate at which searches didn't return any results. The endpoint returns a value for the complete given time range, as well as a value per day. It also returns the count of searches and searches without results used to compute the rates.
-  summary: Returns the rate at which searches didn't return any results.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../../common/parameters.yml#/StartDate'

specs/analytics/paths/search/getSearchesCount.yml

@@ -1,7 +1,9 @@
 get:
+  tags:
+    - search
   operationId: getSearchesCount
+  summary: Get searches count.
   description: Returns the number of searches across the given time range. The endpoint returns a value for the complete given time range, as well as a value per day.
-  summary: Returns the number of searches across the given time range.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../../common/parameters.yml#/StartDate'

specs/analytics/paths/search/getSearchesNoClicks.yml

@@ -1,7 +1,9 @@
 get:
+  tags:
+    - search
   operationId: getSearchesNoClicks
+  summary: Get top searches with no clicks.
   description: Returns top searches that didn't lead to any clicks. Limited to the 1000 most frequent ones. For each search, also returns the average number of found hits.
-  summary: Returns top searches that didn't lead to any clicks.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../../common/parameters.yml#/StartDate'

specs/analytics/paths/search/getSearchesNoResults.yml

@@ -1,7 +1,9 @@
 get:
+  tags:
+    - search
   operationId: getSearchesNoResults
+  summary: Get top searches with no results.
   description: Returns top searches that didn't return any results. Limited to the 1000 most frequent ones.
-  summary: Returns top searches that didn't return any results.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../../common/parameters.yml#/StartDate'

specs/analytics/paths/search/getTopCountries.yml

@@ -1,7 +1,9 @@
 get:
+  tags:
+    - search
   operationId: getTopCountries
+  summary: Get top countries.
   description: Returns top countries. Limited to the 1000 most frequent ones.
-  summary: Returns top countries.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../../common/parameters.yml#/StartDate'

specs/analytics/paths/search/getTopFilterAttributes.yml

@@ -1,7 +1,9 @@
 get:
+  tags:
+    - search
   operationId: getTopFilterAttributes
+  summary: Get top filter attributes.
   description: Returns top filter attributes. Limited to the 1000 most used filters.
-  summary: Returns top filter attributes.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../common/parameters.yml#/Search'

specs/analytics/paths/search/getTopFilterForAttribute.yml

@@ -1,7 +1,9 @@
 get:
+  tags:
+    - search
   operationId: getTopFilterForAttribute
+  summary: Get top filters for the an attribute.
   description: Returns top filters for the given attribute. Limited to the 1000 most used filters.
-  summary: Returns top filters for the given attribute.
   parameters:
     - $ref: '../../common/parameters.yml#/Attribute'
     - $ref: '../../../common/parameters.yml#/Index'

specs/analytics/paths/search/getTopFiltersNoResults.yml

@@ -1,7 +1,9 @@
 get:
+  tags:
+    - search
   operationId: getTopFiltersNoResults
+  summary: Get top filters for a no result search.
   description: Returns top filters with no results. Limited to the 1000 most used filters.
-  summary: Returns top filters with no results.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../common/parameters.yml#/Search'

specs/analytics/paths/search/getTopHits.yml

@@ -1,7 +1,9 @@
 get:
+  tags:
+    - search
   operationId: getTopHits
+  summary: Get top hits.
   description: Returns top hits. Limited to the 1000 most frequent ones.
-  summary: Returns top hits.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../common/parameters.yml#/Search'

specs/analytics/paths/search/getTopSearches.yml

@@ -1,7 +1,9 @@
 get:
+  tags:
+    - search
   operationId: getTopSearches
+  summary: Get top searches.
   description: Returns top searches. Limited to the 1000 most frequent ones. For each search, also returns the average number of hits returned.
-  summary: Returns top searches.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../common/parameters.yml#/ClickAnalytics'

specs/analytics/paths/search/getUsersCount.yml

@@ -1,7 +1,9 @@
 get:
+  tags:
+    - search
   operationId: getUsersCount
+  summary: Get users count.
   description: Returns the distinct count of users across the given time range. The endpoint returns a value for the complete given time range, as well as a value per day.
-  summary: Returns the distinct count of users across the given time range.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../../common/parameters.yml#/StartDate'

specs/analytics/paths/status/getStatus.yml

@@ -1,7 +1,9 @@
 get:
+  tags:
+    - advanced
   operationId: getStatus
+  summary: Get Analytics API status.
   description: Returns the latest update time of the analytics API for a given index. If the index has been recently created and/or no search has been performed yet the updated time will be null.
-  summary: Get latest update time of the analytics API.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
   responses:

specs/analytics/spec.yml

@@ -21,6 +21,24 @@ servers:
 security:
   - appId: []
     apiKey: []
+tags:
+  - name: advanced
+    x-displayName: Advanced
+    description: Advanced operations.
+  - name: click
+    x-displayName: Click Analytics
+    description: Get all click analytics.
+  - name: search
+    x-displayName: Search Analytics
+    description: Get all search analytics.
+x-tagGroups:
+  - name: General
+    tags:
+      - search
+      - click
+  - name: Others
+    tags:
+      - advanced
 paths:
   # ######################
   # ### Custom request ###

specs/common/responses/RequestEntityTooLarge.yml

@@ -0,0 +1,5 @@
+description: Request Entity Too Large.
+content:
+  application/json:
+    schema:
+      $ref: '../schemas/ErrorBase.yml'

specs/common/responses/UnprocessableEntity.yml

@@ -0,0 +1,5 @@
+description: Unprocessable Entity.
+content:
+  application/json:
+    schema:
+      $ref: '../schemas/ErrorBase.yml'

specs/insights/common/enums.yml

@@ -1,4 +1,3 @@
 eventType:
   type: string
-  description: An eventType can be a click, a conversion, or a view.
   enum: [click, conversion, view]