fix(specs): Increase optionalWords visibility in docs (#4559)

Author: gazconroy

specs/common/schemas/CustomRequest.yml

@@ -1,6 +1,6 @@
 customRequest:
   summary: Send requests to the Algolia REST API
-  description: This method allow you to send requests to the Algolia REST API.
+  description: This method lets you send requests to the Algolia REST API.
   parameters:
     - $ref: '#/PathInPath'
     - $ref: '#/Parameters'

specs/common/schemas/IndexSettings.yml

@@ -1218,18 +1218,6 @@ booleanString:
     - 'false'
 
 optionalWords:
-  oneOf:
-    - type: string
-    - type: 'null'
-    - $ref: '#/optionalWordsArray'
-
-optionalWordsArray:
-  type: array
-  items:
-    type: string
-  example:
-    - blue
-    - iphone case
   description: |
     Words that should be considered optional when found in the query.
 
@@ -1248,6 +1236,19 @@ optionalWordsArray:
       For example, with 18 optional words: results 1 to 1,000 require 1 matched word, results 1,001 to 2000 need 4 matched words.
 
     For more information, see [Optional words](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/empty-or-insufficient-results/#creating-a-list-of-optional-words).
+  oneOf:
+    - type: string
+    - type: 'null'
+    - $ref: '#/optionalWordsArray'
+
+optionalWordsArray:
+  type: array
+  items:
+    type: string
+  example:
+    - blue
+    - iphone case
+  description: List of [optional words](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/empty-or-insufficient-results/#creating-a-list-of-optional-words).
   default: []
   x-categories:
     - Query strategy

specs/search/paths/advanced/getLogs.yml

@@ -81,11 +81,25 @@ get:
                       type: string
                       maxLength: 1000
                       description: Response body.
-                      example: |
-                        'n{\n \"results\": [\n  {\n   \"hits\": [\n    {\n     \"name\": \"Amazon - Fire TV Stick\",\n     \"description\": \"Amazon Fire TV Stick connects to your TV's HDMI port. Just grab and go to enjoy Netflix, Prime Instant Video, Hulu Plus, YouTube.com, music, and much more.\",\n     \"brand\": \"Amazon\",\n     \"categories\": [\n      \"TV & Home Theater\",\n      \"Streaming Media Players\"\n     ],\n     \"hierarchicalCategories\": {\n      \"lvl0\": \"TV & Home Theater\",\n      \"lvl1\": \"TV & Home Theater > Streaming Media Players\"\n     },\n     \"type\": \"Streaming media plyr\",\n     \"price\": 39.99,\n     \"price_range\": \"1 - 50\",\n     \"image\": \"https:\/\/cdn-demo.algolia.com\/bestbuy\/9999119_sb.jpg\",\n     \"url\": \"http:\/\/www.bestbuy.com\/site\/amazon-fire-tv-stick\/9999119.p?id=1219460752591&skuId=9999119&cmp=RMX&ky=1uWSHMdQqBeVJB9cXgEke60s5EjfS6M1W\",\n     \"free_shipping\": false,\n     \"popularity\": 9843,\n     \"rating\": 4,\n     \"objectID\": \"9999119\"\n'
+                      example: >
+                        'n{\n "results": [\n  {\n   "hits": [\n   
+                        {\n     "name": "Amazon - Fire TV Stick",\n    
+                        "description": "Amazon Fire TV Stick connects to
+                        your TV's HDMI port. Just grab and go to enjoy
+                        Netflix, Prime Instant Video, Hulu Plus,
+                        YouTube.com, music, and much more.",\n    
+                        "brand": "Amazon",\n     "categories":
+                        [\n      "TV & Home Theater",\n      "Streaming
+                        Media Players"\n     ],\n    
+                        "hierarchicalCategories": {\n      "lvl0": "TV
+                        & Home Theater",\n      "lvl1": "TV & Home
+                        Theater > Streaming Media Players"\n     },\n    
+                        "type": "Streaming media player",\n     "price":
+                        39.99,\n     "price_range": "1
+                        }\n   ]\n  }\n ]\n}'
                     url:
                       type: string
-                      format: uri
+                      format: uri-reference
                       description: URL of the API endpoint.
                       example: /1/indexes
                     ip: