feat(specs): Review OpenAPI common specs (#1692)

Co-authored-by: Kai Welke <kai.welke@algolia.com>
Co-authored-by: Clément Vannicatte <vannicattec@gmail.com>

.eslintrc.cjs

@@ -132,6 +132,12 @@ module.exports = {
             },
           },
         ],
+        'jsdoc/match-description':[
+          'error',
+          {
+            matchDescription: '^\n?([A-Z`\[\\d_][\\s\\S]*[.?!`]\\s*)?$'
+          },
+        ],
       },
     },
     // JS client rules

.github/.cache_version

@@ -1 +1 @@
-0.0.4
+0.0.5

specs/abtesting/common/parameters.yml

@@ -2,40 +2,49 @@
 ID:
   in: path
   name: id
-  description: The A/B test ID.
+  description: Unique A/B test ID.
   required: true
   schema:
     type: integer
+    example: 390
 
 # misc
 index:
   type: string
-  description: The index performing the A/B test.
+  description: A/B test index.
+  example: 'delcourt_production'
 
 abTestID:
   type: integer
-  description: The A/B test ID.
+  description: Unique A/B test ID.
+  example: 224
 
 endAt:
   type: string
-  description: End date for the A/B test expressed as YYYY-MM-DDThh:mm:ssZ.
+  description: End date timestamp in [ISO-8601](https://wikipedia.org/wiki/ISO_8601) format.
+  example: '2023-06-17T00:00:00Z'
 
 createdAt:
   type: string
-  description: Creation date for the A/B test expressed as YYYY-MM-DDThh:mm:ssZ.
+  description: Creation date timestamp in [ISO-8601](https://wikipedia.org/wiki/ISO_8601) format.
+  example: '2023-06-15T15:06:04.249906Z'
 
 updatedAt:
   type: string
-  description: Update date for the A/B test expressed as YYYY-MM-DDThh:mm:ssZ.
+  description: Update date timestamp in [ISO-8601](https://wikipedia.org/wiki/ISO_8601) format.
+  example: '2023-06-15T15:06:44.400601Z'
 
 name:
   type: string
   description: A/B test name.
+  example: 'Custom ranking sales rank test'
 
 description:
   type: string
-  description: The A/B test description.
+  description: A/B test description.
+  example: 'Current production index'
 
 trafficPercentage:
   type: integer
-  description: The traffic percentage for the A/B test.
+  description: A/B test traffic percentage.
+  example: 60

specs/abtesting/common/schemas/ABTest.yml

@@ -1,6 +1,6 @@
 ABTests:
   type: array
-  description: List of A/B tests.
+  description: A/B tests.
   items:
     $ref: '#/ABTest'
 
@@ -13,12 +13,14 @@ ABTest:
     clickSignificance:
       type: number
       format: double
-      description: A/B test significance based on click data. Should be > 0.95 to be considered significant (no matter which variant is winning).
+      description: >
+        [A/B test significance](https://www.algolia.com/doc/guides/ab-testing/what-is-ab-testing/in-depth/how-ab-test-scores-are-calculated/#statistical-significance-or-chance) based on click data. A value of 0.95 or over is considered to be _significant_.
+      example: 1
     conversionSignificance:
       type: number
       format: double
-      description: A/B test significance based on conversion data. Should be > 0.95 to be considered significant (no matter which variant is winning).
-    endAt:
+      description: >
+        [A/B test significance](https://www.algolia.com/doc/guides/ab-testing/what-is-ab-testing/in-depth/how-ab-test-scores-are-calculated/#statistical-significance-or-chance) based on conversion. A value of 0.95 or over is considered to be _significant_.
       $ref: '../parameters.yml#/endAt'
     updatedAt:
       $ref: '../parameters.yml#/updatedAt'
@@ -28,7 +30,8 @@ ABTest:
       $ref: '../parameters.yml#/name'
     status:
       type: string
-      description: status of the A/B test.
+      description: A/B test status.
+      example: 'running'
     variants:
       $ref: 'Variant.yml#/variants'
   required:

specs/abtesting/common/schemas/AddABTestsVariant.yml

@@ -24,6 +24,8 @@ abTestsVariant:
 
 customSearchParams:
   type: object
+  description: Applies search parameters from [a restricted set of options](https://www.algolia.com/doc/api-reference/api-methods/add-ab-test/#method-param-customsearchparameters). Only use this parameter if the two variants use the same index.
+  example: {'typoTolerance': false,'synonyms': false}
   additionalProperties: false
   properties:
     customSearchParameters:

specs/abtesting/common/schemas/Variant.yml

@@ -1,6 +1,6 @@
 variants:
   type: array
-  description: List of A/B test variant.
+  description: A/B test variants.
   items:
     $ref: '#/variant'
 
@@ -10,43 +10,54 @@ variant:
   properties:
     averageClickPosition:
       type: integer
-      description: Average click position for the variant.
+      description: Variant's [average click position](https://www.algolia.com/doc/guides/search-analytics/concepts/metrics/#click-position).
+      example: 0
     clickCount:
       type: integer
-      description: Distinct click count for the variant.
+      description: Number of click events for this variant.
+      example: 65131
     clickThroughRate:
       type: number
       format: double
-      description: Click through rate for the variant.
+      description: Variant's [click-through rate](https://www.algolia.com/doc/guides/search-analytics/concepts/metrics/#click-through-rate).
+      example: 0.22219857724813036
     conversionCount:
       type: integer
-      description: Distinct conversion count for the variant.
+      description: Number of click events for this variant.
+      example: 4785
     conversionRate:
       type: number
       format: double
-      description: Conversion rate for the variant.
+      description: Variant's [conversion rate](https://www.algolia.com/doc/guides/search-analytics/concepts/metrics/#conversion-rate).
+      example: 0.14546725846658964
     description:
       $ref: '../parameters.yml#/description'
     index:
       $ref: '../parameters.yml#/index'
     noResultCount:
-      $ref: '../../../common/parameters.yml#/count'
+      type: integer
+      description: Number of [searches without results](https://www.algolia.com/doc/guides/search-analytics/concepts/metrics/#searches-without-results) for that variant.
+      example: 0
     outlierTrackedSearchesCount:
       type: integer
-      description: Count of the tracked searches attributed to outlier traffic that were removed from the A/B test.
+      description: Number of tracked searches attributed to [outlier traffic](https://www.algolia.com/doc/guides/ab-testing/how-to-read-your-a-b-test-results/#is-the-split-off) that were removed from the A/B test. A _tracked_ search is a search request where the `clickAnalytics` parameter is `true`.
+      example: 0
     outlierUsersCount:
       type: integer
-      description: Count of users attributed to outlier traffic that were removed from the A/B test.
+      description: Number of users attributed to [outlier traffic](https://www.algolia.com/doc/guides/ab-testing/how-to-read-your-a-b-test-results/#is-the-split-off) that were removed from the A/B test.
+      example: 0
     searchCount:
       type: integer
-      description: The number of search during the A/B test.
+      description: Number of searches carried out during the A/B test.
+      example: 86269
     trackedSearchCount:
       $ref: '../../../common/parameters.yml#/trackedSearchCount'
     trafficPercentage:
       $ref: '../parameters.yml#/trafficPercentage'
     userCount:
       type: integer
-      description: The number of user during the A/B test.
+      description: Number of users during the A/B test.
+      example: 55501
   required:
     - userCount
     - trafficPercentage

specs/abtesting/paths/abtest.yml

@@ -2,9 +2,11 @@ get:
   tags:
     - abtest
   operationId: getABTest
-  summary: Get a test.
+  summary: Get A/B test details.
   description: >
-    Returns metadata and metrics for an A/B test.
+    Get specific details for an A/B test.
+
+    To determine the `id` for an A/B test, use the [`listABTests` operation](#tag/abtest/operation/listABTests).
   parameters:
     - $ref: '../common/parameters.yml#/ID'
   responses:
@@ -27,8 +29,11 @@ delete:
   tags:
     - abtest
   operationId: deleteABTest
-  summary: Delete a test.
-  description: Delete a test.
+  summary: Delete an A/B test.
+  description: >
+    Delete an A/B test.
+
+    To determine the `id` for an A/B test, use the [`listABTests` operation](#tag/abtest/operation/listABTests).
   parameters:
     - $ref: '../common/parameters.yml#/ID'
   responses:

specs/abtesting/paths/abtests.yml

@@ -2,11 +2,8 @@ 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: Create an A/B test.
+  description: Creates an A/B test.
   requestBody:
     required: true
     content:
@@ -18,9 +15,9 @@ post:
           properties:
             name:
               $ref: '../common/parameters.yml#/name'
-            variant:
+            variants:
               type: array
-              description: List of 2 variants for the A/B test.
+              description: A/B test variants.
               minItems: 2
               maxItems: 2
               items:
@@ -29,7 +26,7 @@ post:
               $ref: '../common/parameters.yml#/endAt'
           required:
             - name
-            - variant
+            - variants
             - endAt
   responses:
     '200':
@@ -51,22 +48,21 @@ 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.
-
-    When no data has been processed, the metrics will be returned as null.
+  summary: List all A/B tests.
+  description: List all A/B tests.
   parameters:
     - $ref: '../../common/parameters.yml#/Offset'
     - $ref: '../../common/parameters.yml#/Limit'
     - name: indexPrefix
       in: query
-      description: Filters the returned ab tests by any indices starting with the provided prefix that are assigned to either variant of an ab test.
+      description: Only return A/B tests for indices starting with this prefix.
+      example: 'dev_'
       schema:
         type: string
     - name: indexSuffix
       in: query
-      description: Filters the returned ab tests by any indices ending with the provided suffix that are assigned to either variant of an ab test.
+      description: Only return A/B tests for indices ending with this suffix.
+      example: '_development'
       schema:
         type: string
   responses:
@@ -83,10 +79,12 @@ get:
                 $ref: '../common/schemas/ABTest.yml#/ABTests'
               count:
                 type: integer
-                description: Number of A/B tests found for the app.
+                description: Number of A/B tests implemented.
+                example: 10
               total:
                 type: integer
-                description: Number of A/B tests retrievable.
+                description: Number of retrievable A/B tests.
+                example: 12
             required:
               - abtests
               - count

specs/abtesting/paths/stopABTest.yml

@@ -2,13 +2,14 @@ post:
   tags:
     - abtest
   operationId: stopABTest
-  summary: Stop a test.
+  summary: Stop an A/B test.
   description: >
-    Marks the A/B test as stopped.
+    If stopped, the test is over and can't be restarted.
+    There is now only one index, receiving 100% of all search requests.
+    
+    The data gathered for stopped A/B tests is retained.
 
-    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.
+    To determine the `id` for an A/B test, use the [`listABTests` operation](#tag/abtest/operation/listABTests).
   parameters:
     - $ref: '../common/parameters.yml#/ID'
   responses:

specs/abtesting/spec.yml

@@ -23,8 +23,8 @@ security:
     apiKey: []
 tags:
   - name: abtest
-    x-displayName: A/B Testing
-    description: Manage A/B Tests.
+    x-displayName: A/B testing
+    description: Manage A/B tests.
 x-tagGroups:
   - name: General
     tags: