feat(specs): improve API reference documentation (#2831)

Co-authored-by: Pierre Millot <pierre.millot@algolia.com>
Co-authored-by: Clément Vannicatte <vannicattec@gmail.com>

package.json

@@ -24,7 +24,7 @@
     "scripts:test": "yarn workspace scripts test",
     "specs:fix": "eslint --ext=yml specs/$0 --fix",
     "specs:lint": "eslint --ext=yml specs/$0",
-    "website": "yarn cli build specs all -s && cd website && yarn start",
+    "website": "yarn cli build specs all -d -s && cd website && yarn start",
     "website:build": "bash scripts/website/build.sh"
   },
   "devDependencies": {

specs/common/parameters.yml

@@ -2,16 +2,16 @@
 IndexName:
   name: indexName
   in: path
-  description: Index on which to perform the request.
+  description: Name of the index on which to perform the operation.
   required: true
   schema:
     type: string
-    example: myIndexName
+    example: YourIndexName
 
 ObjectID:
   name: objectID
   in: path
-  description: Unique record (object) identifier.
+  description: Unique record identifier.
   required: true
   schema:
     type: string
@@ -21,7 +21,7 @@ ObjectID:
 Index:
   in: query
   name: index
-  description: Index name to target.
+  description: Index name.
   required: true
   schema:
     type: string
@@ -30,33 +30,34 @@ Index:
 StartDate:
   in: query
   name: startDate
-  description: Start date (a string in the format `YYYY-MM-DD`) of the period to analyze.
+  description: Start date (`YYYY-MM-DD`) of the period to analyze.
   schema:
     type: string
+    format: date
     example: 2022-09-19
-    pattern: ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$
 
 EndDate:
   in: query
   name: endDate
-  description: End date (a string in the format `YYYY-MM-DD`) of the period to analyze.
+  description: End date (`YYYY-MM-DD`) of the period to analyze.
   schema:
     type: string
+    format: date
     example: 2023-01-21
-    pattern: ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$
 
 ForwardToReplicas:
   in: query
   name: forwardToReplicas
-  description: Indicates whether changed index settings are forwarded to the replica indices.
+  description: Whether changes are applied to replica indices.
   schema:
     type: boolean
 
 Page:
   in: query
   name: page
-  description: >
-    Returns the requested page number. The page size is determined by the `hitsPerPage` parameter. You can see the number of available pages in the `nbPages` response attribute. When `page` is null, the API response is not paginated.
+  description: |
+    Requested page of the API response.
+    If `null`, the API response is not paginated.
   schema:
     type: integer
     minimum: 0
@@ -66,8 +67,9 @@ Page:
 PageDefault0:
   in: query
   name: page
-  description: >
-    Returns the requested page number (the first page is 0). Page size is set by `hitsPerPage`. When null, there's no pagination.
+  description: |
+    Requested page of the API response.
+    If `null`, the API response is not paginated.
   schema:
     type: integer
     nullable: true
@@ -77,32 +79,37 @@ PageDefault0:
 HitsPerPage:
   in: query
   name: hitsPerPage
-  description: Maximum number of hits per page.
+  description: Number of hits per page.
   schema:
     type: integer
     default: 100
 
 Offset:
   in: query
   name: offset
-  description: Position of the starting record. Used for paging. 0 is the first record.
+  description: Position of the first item to return.
   schema:
     type: integer
     default: 0
+    minimum: 0
 
 Limit:
   in: query
   name: limit
-  description: Number of records to return (page size).
+  description: Number of items to return.
   schema:
     type: integer
     default: 10
 
 # misc
 objectID:
   type: string
-  description: Unique object identifier.
-  example: 'product-1'
+  description: Unique record identifier.
+
+ruleID:
+  title: objectID
+  type: string
+  description: Unique identifier of a rule object.
 
 id:
   type: string
@@ -112,7 +119,7 @@ id:
 indexName:
   type: string
   example: products
-  description: Algolia index name.
+  description: Index name.
 
 hitsPerPage:
   type: integer
@@ -123,13 +130,13 @@ hitsPerPage:
 
 query:
   type: string
-  description: Full-text query.
+  description: Search query.
   default: ''
 
 page:
   type: integer
   minimum: 0
-  description: Requested page (the first page is page 0).
+  description: Requested page of the API response.
 
 trackedSearchCount:
   type: integer

specs/common/responses/common.yml

@@ -2,22 +2,24 @@ taskID:
   type: integer
   format: int64
   example: 1514562690001
-  description: >
+  description: |
     Unique identifier of a task.
 
-    A successful API response means that a task was added to a queue. It might not run immediately. You can check the task's progress with the `task` operation and this `taskID`.
+    A successful API response means that a task was added to a queue. It might not run immediately. You can check the task's progress with the [`task` operation](#tag/Indices/operation/getTask) and this `taskID`.
 
 objectIDs:
   type: array
   items:
     type: string
-  example: ['record-1','record-2']
-  description: Unique object (record) identifiers.
+  example:
+    - record-1
+    - record-2
+  description: Unique record identifiers.
 
 createdAt:
   type: string
-  example: '2023-07-04T12:49:15Z'
-  description: Timestamp of creation in [ISO-8601](https://wikipedia.org/wiki/ISO_8601) format.
+  example: 2023-07-04T12:49:15Z
+  description: Timestamp of creation in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format.
 
 createdAtTimestamp:
   type: integer
@@ -27,10 +29,10 @@ createdAtTimestamp:
 
 updatedAt:
   type: string
-  example: '2023-07-04T12:49:15Z'
+  example: 2023-07-04T12:49:15Z
   description: Timestamp of the last update in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format.
 
 deletedAt:
   type: string
-  example: '2023-06-27T14:42:38.831Z'
+  example: 2023-06-27T14:42:38.831Z
   description: Timestamp of deletion in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format.

specs/common/schemas/HighlightResult.yml

@@ -1,6 +1,6 @@
 highlightResultOption:
   type: object
-  description: Show highlighted section and words matched on a query.
+  description: Surround words that match the query with HTML tags for highlighting.
   additionalProperties: false
   properties:
     value:
@@ -9,7 +9,7 @@ highlightResultOption:
       $ref: '#/matchLevel'
     matchedWords:
       type: array
-      description: List of words from the query that matched the object.
+      description: List of matched words from the search query.
       example: ['action']
       items:
         type: string
@@ -23,23 +23,24 @@ highlightResultOption:
 
 highlightedValue:
   type: string
-  description: Markup text with `facetQuery` matches highlighted.
+  description: Highlighted attribute value, including HTML tags.
   example: '<em>George</em> <em>Clo</em>oney'
 
 matchLevel:
   type: string
-  description: Indicates how well the attribute matched the search query.
+  description: Whether the whole query string matches or only a part.
   enum: [none, partial, full]
 
 highlightResultOptionMap:
   type: object
-  description: Show highlighted section and words matched on a query.
+  description: Surround words that match the query with HTML tags for highlighting.
   additionalProperties:
+    x-additionalPropertiesName: attribute
     $ref: '#/highlightResultOption'
 
 highlightResultOptionArray:
   type: array
-  description: Show highlighted section and words matched on a query.
+  description: Surround words that match the query with HTML tags for highlighting.
   items:
     $ref: '#/highlightResultOption'
 
@@ -51,6 +52,7 @@ highlightResult:
 
 highlightResultMap:
   type: object
-  description: Show highlighted section and words matched on a query.
+  description: Surround words that match the query with HTML tags for highlighting.
   additionalProperties:
+    x-additionalPropertiesName: attribute
     $ref: '#/highlightResult'