fix: search index spec (#8)

Co-authored-by: Clément Vannicatte <[email protected]>

Author: Samuel Bodin

.env.example

@@ -0,0 +1,3 @@
+ALGOLIA_APPLICATION_ID=""
+ALGOLIA_ADMIN_KEY=""
+ALGOLIA_SEARCH_KEY=""

app.ts

@@ -1,12 +1,15 @@
-import { searchClient } from 'algoliasearch-client-javascript';
+import { searchClient, HttpError } from 'algoliasearch-client-javascript';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+const appId = process.env.ALGOLIA_APPLICATION_ID || '**** APP_ID *****';
+const apiKey = process.env.ALGOLIA_SEARCH_KEY || '**** SEARCH_API_KEY *****';
 
-const appId = process.env.ALGOLIA_APPLICATION_ID_1 || '**** APP_ID *****';
-const apiKey = process.env.ALGOLIA_ADMIN_KEY_1 || '**** API_KEY *****';
 // Init client with appId and apiKey
 const client = new searchClient(appId, apiKey);
 
-async function testClient() {
-  // test openapi gen
+async function testMultiQueries() {
   try {
     const res = await client.multipleQueries({
       requests: [
@@ -17,10 +20,31 @@ async function testClient() {
       ],
     });
 
-    console.log('[1-RESPONSE]', res);
+    console.log(`[OK]`, res);
   } catch (e) {
-    console.error('[1-ERROR]', e);
+    if (e instanceof HttpError) {
+      return console.log(`[${e.statusCode} - ${e.response.statusMessage}]`, e.response);
+    }
+
+    console.log('[ERROR]', e);
+  }
+}
+
+async function testSearch() {
+  try {
+    const res = await client.search('docsearch', {
+      query: 'crawler',
+    });
+
+    console.log(`[OK]`, res);
+  } catch (e) {
+    if (e instanceof HttpError) {
+      return console.log(`[${e.statusCode} - ${e.response.statusMessage}]`, e.response);
+    }
+
+    console.log('[ERROR]', e);
   }
 }
 
-testClient();
+// testMultiQueries();
+testSearch();

openapi_spec/paths/indexes/batch.yml

@@ -12,6 +12,7 @@ post:
         schema:
           title: batchObject
           type: object
+          additionalProperties: false
           properties:
             requests:
               type: array

openapi_spec/paths/indexes/multipleQueries.yml

@@ -24,8 +24,7 @@ post:
                     example: products
                     description: The Algolia index name
                   query:
-                    type: string
-                    description: The query to search for
+                    $ref: ../../schemas/SearchParams.yml#/searchParams/properties/query
                   type:
                     type: string
                     enum: [default, facet]
@@ -57,22 +56,8 @@ post:
               results:
                 type: array
                 items:
-                  type: object
-                  additionalProperties: false
-                  properties:
-                    hits:
-                      type: array
-                      items:
-                        type: object
-                        additionalProperties: false
-                        properties:
-                          objectID:
-                            $ref: '../../responses/common.yml#/objectID'
-                    nbHits:
-                      type: integer
-                    queryID:
-                      $ref: '../../responses/common.yml#/queryID'
+                  $ref: ../../schemas/SearchResponse.yml#/searchResponse
     '400':
-      $ref: '../../responses/BadRequest.yml'
+      $ref: ../../responses/BadRequest.yml
     '404':
-      $ref: '../../responses/IndexNotFound.yml'
+      $ref: ../../responses/IndexNotFound.yml

openapi_spec/paths/indexes/search.yml

@@ -6,32 +6,22 @@ post:
   parameters:
     - $ref: '../../parameters.yml#/IndexName'
   requestBody:
-    $ref: '../../schemas/SearchParams.yml'
+    required: true
+    content:
+      application/json:
+        schema:
+          oneOf:
+            - $ref: ../../schemas/SearchParams.yml#/searchParams
+            - $ref: ../../schemas/SearchParams.yml#/searchParamsString
   responses:
     '200':
       description: OK
       content:
         application/json:
           schema:
             title: singleQueryResponse
-            type: object
-            additionalProperties: false
-            properties:
-              hits:
-                type: array
-                items:
-                  type: object
-                  additionalProperties: false
-                  properties:
-                    objectID:
-                      $ref: '../../responses/common.yml#/objectID'
-              nbHits:
-                type: integer
-              queryID:
-                type: string
-                pattern: '^[a-f0-9]{32}$'
-                example: 43b15df305339e827f0ac0bdc5ebcaa7
+            $ref: ../../schemas/SearchResponse.yml#/searchResponse
     '400':
-      $ref: '../../responses/BadRequest.yml'
+      $ref: ../../responses/BadRequest.yml
     '404':
-      $ref: '../../responses/IndexNotFound.yml'
+      $ref: ../../responses/IndexNotFound.yml

openapi_spec/responses/common.yml

@@ -1,15 +1,26 @@
 taskID:
   type: integer
   description: taskID of the indexing task to wait for.
+
 objectID:
   type: string
   description: Unique identifier of the object
+
 objectIDs:
   type: array
   items:
     type: string
   description: List of objectID
+
 queryID:
   type: string
   pattern: '^[a-f0-9]{32}$'
   example: 43b15df305339e827f0ac0bdc5ebcaa7
+
+abTestID:
+  type: integer
+  description: If a search encounters an index that is being A/B tested, abTestID reports the ongoing A/B test ID.
+
+abTestVariantID:
+  type: integer
+  description: If a search encounters an index that is being A/B tested, abTestVariantID reports the variant ID of the index used.

openapi_spec/schemas/IndexSettingsParams.yml

@@ -0,0 +1,85 @@
+allowCompressionOfIntegerArray:
+  type: boolean
+  description: Enables compression of large integer arrays.
+  default: false
+
+attributeForDistinct:
+  type: string
+  description: Name of the de-duplication attribute to be used with the distinct feature.
+  default: null
+
+attributesToTransliterate:
+  type: array
+  items:
+    type: string
+  description: Specify on which attributes to apply transliteration.
+
+camelCaseAttributes:
+  type: array
+  items:
+    type: string
+  description: List of attributes on which to do a decomposition of camel case words.
+  default: []
+
+customNormalization:
+  type: object
+  additionalProperties: true
+  description: Override the default normalization handled by the engine.
+  default: {}
+
+decompoundedAttributes:
+  type: object
+  additionalProperties: true
+  description: Specify on which attributes in your index Algolia should apply word segmentation, also known as decompounding.
+  default: {}
+
+disablePrefixOnAttributes:
+  type: array
+  items:
+    type: string
+  description: List of attributes on which you want to disable prefix matching.
+  default: []
+
+disableTypoToleranceOnWords:
+  type: array
+  items:
+    type: string
+  description: A list of words for which you want to turn off typo tolerance.
+  default: []
+
+filterPromotes:
+  type: boolean
+  description: Whether promoted results should match the filters of the current search, except for geographic filters.
+  default: false
+
+indexLanguages:
+  type: array
+  items:
+    type: string
+  description: Sets the languages at the index level for language-specific processing such as tokenization and normalization.
+  default: []
+
+numericAttributesForFiltering:
+  type: array
+  items:
+    type: string
+  description: List of numeric attributes that can be used as numerical filters.
+  default: null
+
+paginationLimitedTo:
+  type: integer
+  description: Set the maximum number of hits accessible via pagination.
+  default: 1000
+
+userData:
+  type: object
+  additionalProperties: true
+  description: Lets you store custom data in your indices.
+  default: {}
+
+replicas:
+  type: array
+  items:
+    type: string
+  description: Creates replicas, exact copies of an index.
+  default: []

openapi_spec/schemas/Record.yml

@@ -0,0 +1,102 @@
+record:
+  type: object
+  description: A single record
+  additionalProperties: true
+  required:
+    - objectID
+  properties:
+    objectID:
+      $ref: '../responses/common.yml#/objectID'
+    _highlightResult:
+      $ref: '#/highlightResult'
+    _snippetResult:
+      $ref: '#/snippetResult'
+    _rankingInfo:
+      $ref: '#/rankingInfo'
+    _distinctSeqID:
+      type: number
+
+# Props
+highlightResult:
+  type: object
+  additionalProperties: false
+  properties:
+    value:
+      type: string
+      description: 'Markup text with occurrences highlighted.'
+      example: '<em>George</em> <em>Clo</em>oney'
+    matchLevel:
+      type: string
+      description: 'Indicates how well the attribute matched the search query.'
+      enum: [none, partial, full]
+    matchedWords:
+      type: array
+      description: List of words from the query that matched the object.
+      items:
+        type: string
+    fullyHighlighted:
+      type: boolean
+      description: 'Whether the entire attribute value is highlighted.'
+
+snippetResult:
+  type: object
+  additionalProperties: false
+  properties:
+    value:
+      type: string
+      description: 'Markup text with occurrences highlighted.'
+      example: '<em>George</em> <em>Clo</em>oney...'
+    matchLevel:
+      type: string
+      description: 'Indicates how well the attribute matched the search query.'
+      enum: [none, partial, full]
+
+rankingInfo:
+  type: object
+  additionalProperties: false
+  properties:
+    filters:
+      type: integer
+      description: 'This field is reserved for advanced usage.'
+    firstMatchedWord:
+      type: integer
+      description: 'Position of the most important matched attribute in the attributes to index list.'
+    geoDistance:
+      type: integer
+      description: 'Distance between the geo location in the search query and the best matching geo location in the record, divided by the geo precision (in meters).'
+    geoPrecision:
+      type: integer
+      description: 'Precision used when computing the geo distance, in meters.'
+    matchedGeoLocation:
+      type: object
+      additionalProperties:
+        type: object
+        additionalProperties: false
+        properties:
+          lat:
+            type: float
+            description: 'Latitude of the matched location.'
+          lng:
+            type: float
+            description: 'Longitude of the matched location.'
+          distance:
+            type: integer
+            description: 'Distance between the matched location and the search location (in meters).'
+    nbExactWords:
+      type: integer
+      description: 'Number of exactly matched words.'
+    nbTypos:
+      type: integer
+      description: 'Number of typos encountered when matching the record.'
+    promoted:
+      type: boolean
+      description: 'Present and set to true if a Rule promoted the hit.'
+    proximityDistance:
+      type: integer
+      description: 'When the query contains more than one word, the sum of the distances between matched words (in meters).'
+    userScore:
+      type: integer
+      description: 'Custom ranking for the object, expressed as a single integer value.'
+    word:
+      type: integer
+      description: 'Number of matched words, including prefixes and typos.'

openapi_spec/schemas/RequestOptions.yml

@@ -0,0 +1,23 @@
+# Not used yet
+
+# timeouts:
+#   type: object
+#   additionalProperties: false
+#   properties:
+#     connect:
+#       type: integer
+#       description: 'Connection timeout in seconds.'
+#       example: 2
+#     read:
+#       type: integer
+#       description: 'Read timeout in seconds.'
+#       example: 5
+#     write:
+#       type: integer
+#       description: 'Write timeout in seconds.'
+#       example: 30
+
+# X-Algolia-UserToken:
+#   type: string
+# X-Forwarded-For:
+#   type: string