docs(specs): Review OpenAPI Search API (dictionary operations)

specs/search/paths/dictionaries/batchDictionaryEntries.yml

@@ -2,7 +2,7 @@ post:
   tags:
     - Dictionaries
   operationId: batchDictionaryEntries
-  description: Send a batch of dictionary entries.
+  description: Add or remove a batch of dictionary entries.
   summary: Batch dictionary entries.
   parameters:
     - $ref: 'common/parameters.yml#/DictionaryName'
@@ -12,7 +12,8 @@ post:
       application/json:
         schema:
           title: batchDictionaryEntriesParams
-          description: The `batchDictionaryEntries` parameters.
+          description: >
+            `batchDictionaryEntries` parameters.
           type: object
           required:
             - requests
@@ -21,10 +22,10 @@ post:
             clearExistingDictionaryEntries:
               type: boolean
               default: false
-              description: When `true`, start the batch by removing all the custom entries from the dictionary.
+              description: If `true`, delete all custom entries in the dictionary and then add the ones sent with this request.
             requests:
               type: array
-              description: List of operations to batch. Each operation is described by an `action` and a `body`.
+              description: Operations to batch.
               items:
                 title: batchDictionaryEntriesRequest
                 type: object

specs/search/paths/dictionaries/common/parameters.yml

@@ -2,7 +2,7 @@
 DictionaryName:
   in: path
   name: dictionaryName
-  description: The dictionary to search in.
+  description: Dictionary to search in.
   required: true
   schema:
     $ref: '#/dictionaryType'
@@ -13,12 +13,14 @@ dictionaryType:
 
 # misc
 language:
-  description: Language ISO code supported by the dictionary (e.g., "en" for English).
+  description: >
+    [Supported language ISO code](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/).
+  example: 'en'
   type: string
 
 standardEntries:
-  description: Map of language ISO code supported by the dictionary (e.g., "en" for English) to a boolean value.
-  type: object
+  description: >
+    Maps a [supported language ISO code](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/) to a boolean value (for example, `'fr': false`). If `true` Algolia's built-in [stop words](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-stop-words/) for that language have been turned off.
   additionalProperties: false
   properties:
     plurals:
@@ -29,7 +31,9 @@ standardEntries:
       $ref: '#/standardEntry'
 
 standardEntry:
-  description: Language ISO code.
+  description: Language ISO code and boolean.
+  example: >
+    {'fr': false}
   type: object
   nullable: true
   additionalProperties:

specs/search/paths/dictionaries/common/schemas/Languages.yml

@@ -1,6 +1,6 @@
 languages:
   type: object
-  description: A dictionary language.
+  description: Dictionary language.
   additionalProperties: false
   required:
     - plurals
@@ -20,6 +20,9 @@ dictionaryLanguage:
   nullable: true
   description: Custom entries for a dictionary.
   properties:
-    nbCustomEntires:
-      description: "When nbCustomEntries is set to 0, the user didn't customize the dictionary. The dictionary is still supported with standard, Algolia-provided entries."
+    nbCustomEntries:
+      description: >
+        If `0`, the dictionary hasn't been customized and only contains standard entries provided by Algolia.
+
+        If `null`, that feature isn't available or isn't supported for that language.
       type: integer

specs/search/paths/dictionaries/common/schemas/SearchDictionaryEntriesResponse.yml

@@ -16,28 +16,51 @@ searchDictionaryEntriesResponse:
 
 dictionaryEntry:
   type: object
-  description: A dictionary entry.
+  description: Dictionary entry.
   additionalProperties: true
   required:
     - objectID
     - language
   properties:
     objectID:
-      $ref: '../../../../../common/parameters.yml#/objectID'
+      type: string
+      description: Unique identifier for a dictionary object.
+      example: 'under'
     language:
       type: string
-      description: Language ISO code supported by the dictionary (e.g., "en" for English).
+      description: >
+        [Supported language ISO code](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/).
+      example: 'de'
     word:
       type: string
-      description: The word of the dictionary entry.
+      description: >
+        Dictionary entry word. Usage depends on the type of dictionary entry.
+
+        **`stopwordEntry`**
+
+        The stop word you want to add or update. If the entry already exists in Algolia's standard dictionary, you can override its behavior by adding it to the custom dictionary and setting its `state` to `disabled`.
+
+        **`compoundEntry`**
+
+        When `decomposition` is empty: adds `word` as a compound atom.
+        For example, atom “kino” decomposes the query “kopfkino” into "kopf" and "kino".
+        
+        When `decomposition` isn't empty: creates a decomposition exception.
+        For example, when decomposition is set to the ["hund", "hutte"] exception, "hundehutte" decomposes into “hund” and “hutte”, discarding the linking "e".
+      example: 'down'
     words:
       type: array
-      description: The words of the dictionary entry.
+      description: >
+        Compound dictionary [word declensions](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-plurals-and-other-declensions/).
+        
+        If the entry already exists in Algolia's standard dictionary, you can override its behavior by adding it to the custom dictionary and setting its `state` to `disabled`.
+      example: ['cheval','chevaux']
       items:
         type: string
     decomposition:
       type: array
-      description: A decomposition of the word of the dictionary entry.
+      description: For compound entries, governs the behavior of the `word` parameter.
+      example: ['kopf','schmerz','tablette']
       items:
         type: string
     state:

specs/search/paths/dictionaries/dictionarySettings.yml

@@ -2,8 +2,8 @@ get:
   tags:
     - Dictionaries
   operationId: getDictionarySettings
-  description: Retrieve dictionaries settings. The API stores languages whose standard entries are disabled. Fetch settings does not return false values.
-  summary: Retrieve dictionaries settings.
+  description: Get the languages for which [stop words are turned off](#tag/Dictionaries/operation/setDictionarySettings).
+  summary: Get stop word settings.
   responses:
     '200':
       description: OK
@@ -31,8 +31,8 @@ put:
   tags:
     - Dictionaries
   operationId: setDictionarySettings
-  description: Set dictionaries settings.
-  summary: Set dictionaries settings.
+  description: Set stop word settings for a specific language.
+  summary: Set stop word settings.
   requestBody:
     required: true
     content:
@@ -41,7 +41,7 @@ put:
           title: dictionarySettingsParams
           type: object
           additionalProperties: false
-          description: Disable the builtin Algolia entries for a type of dictionary per language.
+          description: Enable or turn off the built-in Algolia stop words for a specific language.
           required:
             - disableStandardEntries
           properties:

specs/search/paths/dictionaries/getDictionaryLanguages.yml

@@ -2,7 +2,7 @@ get:
   tags:
     - Dictionaries
   operationId: getDictionaryLanguages
-  description: List dictionaries supported per language.
+  description: Lists Algolia's [supported languages](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/) and any customizations applied to each language's [stop word](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-stop-words/), [plural](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-plurals-and-other-declensions/), and [segmentation (compound)](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-segmentation/) features.
   summary: List available languages.
   responses:
     '200':

specs/search/paths/dictionaries/searchDictionaryEntries.yml

@@ -4,8 +4,8 @@ post:
   operationId: searchDictionaryEntries
   x-use-read-transporter: true
   x-cacheable: true
-  description: Search the dictionary entries.
-  summary: Search a dictionary entries.
+  description: Search for standard and [custom](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-stop-words/) entries in the [stop words](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-stop-words/), [plurals](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-plurals-and-other-declensions/), or [segmentation (compounds)](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-segmentation/) dictionaries.
+  summary: Search dictionary entries.
   parameters:
     - $ref: 'common/parameters.yml#/DictionaryName'
   requestBody:
@@ -14,7 +14,8 @@ post:
       application/json:
         schema:
           title: searchDictionaryEntriesParams
-          description: The `searchDictionaryEntries` parameters.
+          description: >
+            `searchDictionaryEntries` parameters.
           type: object
           required:
             - query