fix(specs): update documentation for consistency (#2976)

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

specs/analytics/common/parameters.yml

@@ -316,7 +316,7 @@ x-ratelimit-remaining:
     type: integer
 
 x-ratelimit-reset:
-  description: Timestamp in Unix epoch time when the rate limit will reset.
+  description: Timstamp when the rate limit will reset, measured in seconds since the Unix epoch.
   example: 1710682486
   schema:
     type: integer

specs/analytics/spec.yml

@@ -8,13 +8,9 @@ info:
   description: |
     The Analytics API gives you access to metrics related to your Algolia search experience.
 
-    # Availability
+    ## Base URLs
 
-    Access to this API is available as part of the [Premium or Elevate plans](https://www.algolia.com/pricing).
-
-    # Base URLs
-
-    The base URLs for making requests to the Analytics API are:
+    The base URLs for requests to the Analytics API are:
 
     - `https://analytics.us.algolia.com` (alias: `https://analytics.algolia.com`)
     - `https://analytics.de.algolia.com`
@@ -23,42 +19,38 @@ info:
 
     **All requests must use HTTPS.**
 
-    # Authentication
+    ## Availability and authentication
+
+    Access to the Analytics API is available as part of the [Premium or Elevate plans](https://www.algolia.com/pricing).
 
     To authenticate your API requests, add these headers:
 
-    <dl>
-    <dt><code>x-algolia-application-id</code></dt>
-    <dd>Your Algolia application ID.</dd>
-    <dt><code>x-algolia-api-key</code></dt>
-    <dd>
-    An API key with the necessary permissions to make the request.
-    The required access control list (ACL) to make a request is listed in each endpoint's reference.
-    </dd>
-    </dl>
+    - `x-algolia-application-id`. Your Algolia application ID.
+    - `x-algolia-api-key`. An API key with the necessary permissions to make the request.
+      The required access control list (ACL) to make a request is listed in each endpoint's reference.
 
     You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account).
 
-    # Rate limits
+    ## Rate limits
 
     You can make up to **100 requests per minute per app** to the Analytics API.
     The response includes headers with information about the limits.
 
-    # Parameters
+    ## Parameters
 
     Query parameters must be [URL-encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding).
     Non-ASCII characters must be UTF-8 encoded.
     Plus characters (`+`) are interpreted as spaces.
 
-    # Response status and errors
+    ## Response status and errors
 
     The Analytics API returns JSON responses.
     Since JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response.
 
     Successful responses return a `2xx` status. Client errors return a `4xx` status. Server errors are indicated by a `5xx` status.
     Error responses have a `message` property with more information.
 
-    # Version
+    ## Version
 
     The current version of the Analytics API is version 2, as indicated by the `/2/` in each endpoint's URL.
 

specs/common/parameters.yml

@@ -30,15 +30,33 @@ Index:
 StartDate:
   in: query
   name: startDate
-  description: Start date (`YYYY-MM-DD`) of the period to analyze.
+  description: Start date of the period to analyze, in `YYYY-MM-DD` format.
+  schema:
+    type: string
+    example: 2022-09-19
+
+StartDateRequired:
+  in: query
+  name: startDate
+  description: Start date of the period to analyze, in `YYYY-MM-DD` format.
+  required: true
   schema:
     type: string
     example: 2022-09-19
 
 EndDate:
   in: query
   name: endDate
-  description: End date (`YYYY-MM-DD`) of the period to analyze.
+  description: End date of the period to analyze, in `YYYY-MM-DD` format.
+  schema:
+    type: string
+    example: 2023-01-21
+
+EndDateRequired:
+  in: query
+  name: endDate
+  description: End date of the period to analyze, in `YYYY-MM-DD` format.
+  required: true
   schema:
     type: string
     example: 2023-01-21

specs/common/responses/common.yml

@@ -19,28 +19,30 @@ objectIDs:
 createdAt:
   type: string
   example: 2023-07-04T12:49:15Z
-  description: Timestamp of creation in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format.
+  description: Date and time when the object was created, in RFC 3339 format.
 
 createdAtTimestamp:
   type: integer
   format: int64
   example: 1656345570000
-  description: Timestamp of creation in milliseconds in [Unix epoch time](https://wikipedia.org/wiki/Unix_time).
+  description: Timestamp when the object was created, in milliseconds since the Unix epoch.
 
 updatedAt:
   type: string
   example: 2023-07-04T12:49:15Z
-  description: Timestamp of the last update in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format.
+  description: Date and time when the object was updated, in RFC 3339 format.
 
 updatedAtNullable:
-  type: string
-  example: 2023-07-04T12:49:15Z
-  nullable: true
-  description: |
-    Timestamp of the last update in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format.
-    If null, no update was performed yet.
+  default: null
+  oneOf:
+    - type: string
+      example: 2023-07-04T12:49:15Z
+      description: |
+        Date and time when the object was updated, in RFC 3339 format.
+    - type: 'null'
+      description: If null, this object wasn't updated yet.
 
 deletedAt:
   type: string
   example: 2023-06-27T14:42:38.831Z
-  description: Timestamp of deletion in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format.
+  description: Date and time when the object was deleted, in RFC 3339 format.