fix(spec): cleanup summary

.eslintrc.js

@@ -43,7 +43,7 @@ module.exports = {
       overrides: [{
         files: ['specs/**/*.yml'],
         rules: {
-          "automation-custom/description-dot": "error",
+          "automation-custom/end-with-dot": "error",
           "automation-custom/single-quote-ref": "error",
         },
         overrides: [

.github/.cache_version

@@ -1 +1 @@
-9.2.0
+9.2.1

eslint/package.json

@@ -7,7 +7,7 @@
     "src/**.ts"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "rm -rf dist/ && tsc",
     "test": "jest"
   },
   "devDependencies": {

eslint/src/index.ts

@@ -1,9 +1,9 @@
-import { descriptionDot } from './rules/descriptionDot';
+import { endWithDot } from './rules/endWithDot';
 import { outOfLineEnum } from './rules/outOfLineEnum';
 import { singleQuoteRef } from './rules/singleQuoteRef';
 
 const rules = {
-  'description-dot': descriptionDot,
+  'end-with-dot': endWithDot,
   'out-of-line-enum': outOfLineEnum,
   'single-quote-ref': singleQuoteRef,
 };

eslint/src/rules/descriptionDot.ts → eslint/src/rules/endWithDot.ts

@@ -1,15 +1,14 @@
-/* eslint-disable no-console */
 import type { Rule } from 'eslint';
 
 import { isBLockScalar, isPairWithKey, isScalar } from '../utils';
 
-export const descriptionDot: Rule.RuleModule = {
+export const endWithDot: Rule.RuleModule = {
   meta: {
     docs: {
-      description: 'description must end with a dot',
+      description: '`description`, `summary` must end with a dot',
     },
     messages: {
-      descriptionNoDot: 'description does not end with a dot',
+      endWithDot: 'content does not end with a dot',
     },
     fixable: 'code',
   },
@@ -20,12 +19,17 @@ export const descriptionDot: Rule.RuleModule = {
 
     return {
       YAMLPair(node): void {
-        if (!isPairWithKey(node, 'description')) {
+        if (
+          !isPairWithKey(node, 'description') &&
+          !isPairWithKey(node, 'summary')
+        ) {
           return;
         }
+
         if (!isScalar(node.value)) {
           return;
         }
+
         const value = node.value;
         if (
           typeof value.value !== 'string' ||
@@ -46,7 +50,7 @@ export const descriptionDot: Rule.RuleModule = {
         }
         context.report({
           node: node as any,
-          messageId: 'descriptionNoDot',
+          messageId: 'endWithDot',
           fix(fixer) {
             return fixer.insertTextAfterRange(
               [0, value.range[1] - toTrim],

eslint/tests/descriptionDot.test.ts → eslint/tests/endWithDot.ts

@@ -1,12 +1,12 @@
 import { RuleTester } from 'eslint';
 
-import { descriptionDot } from '../src/rules/descriptionDot';
+import { endWithDot } from '../src/rules/endWithDot';
 
 const ruleTester = new RuleTester({
   parser: require.resolve('yaml-eslint-parser'),
 });
 
-ruleTester.run('description-dot', descriptionDot, {
+ruleTester.run('end-with-dot', endWithDot, {
   valid: [
     `
 simple:

scripts/buildSpecs.ts

@@ -19,7 +19,10 @@ const ALGOLIASEARCH_LITE_OPERATIONS = [
   'post',
 ];
 
-async function propagateTagsToOperations({
+/**
+ * This function will transform properties in the bundle depending on the context.
+ */
+async function transformBundle({
   bundledPath,
   withDoc,
   clientName,
@@ -50,16 +53,23 @@ async function propagateTagsToOperations({
       // because open-api-generator will use this to determine the name of the client
       specMethod.tags = [clientName];
 
-      if (
-        !withDoc ||
-        !bundledDocSpec ||
-        !bundledDocSpec.paths[pathKey][method].tags
-      ) {
+      // Doc special cases
+      if (!withDoc || !bundledDocSpec) {
+        continue;
+      }
+
+      const docMethod = bundledDocSpec.paths[pathKey][method];
+      if (docMethod.summary) {
+        // Remove dot at the end of summary for better sidebar display
+        docMethod.summary = docMethod.summary.replace(/\.$/gm, '');
+      }
+
+      if (!docMethod.tags) {
         continue;
       }
 
       // Checks that specified tags are well defined at root level
-      for (const tag of bundledDocSpec.paths[pathKey][method].tags) {
+      for (const tag of docMethod.tags) {
         if (tag === clientName || (alias && tag === alias)) {
           return;
         }
@@ -162,7 +172,7 @@ async function buildLiteSpec({
   const liteBundledPath = `specs/bundled/${spec}.${outputFormat}`;
   await fsp.writeFile(toAbsolutePath(liteBundledPath), yaml.dump(parsed));
 
-  await propagateTagsToOperations({
+  await transformBundle({
     bundledPath: toAbsolutePath(liteBundledPath),
     clientName: spec,
     // Lite does not need documentation because it's just a subset
@@ -223,7 +233,7 @@ async function buildSpec(
 
   // Add the correct tags to be able to generate the proper client
   if (!isLite) {
-    await propagateTagsToOperations({
+    await transformBundle({
       bundledPath: toAbsolutePath(bundledPath),
       clientName: spec,
       withDoc: BUNDLE_WITH_DOC,

specs/search/paths/advanced/getLogs.yml

@@ -2,8 +2,8 @@ get:
   tags:
     - Advanced
   operationId: getLogs
-  description: Return the lastest log entries.
-  summary: Return the lastest log entries.
+  description: Return the latest log entries.
+  summary: Return the latest log entries.
   parameters:
     - name: offset
       in: query

specs/search/paths/advanced/getTask.yml

@@ -3,7 +3,7 @@ get:
     - Indices
   operationId: getTask
   description: Check the current status of a given task.
-  summary: Check the current status of a given task.
+  summary: Check the status of a task.
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
     - name: taskID

specs/search/paths/dictionaries/batchDictionaryEntries.yml

@@ -3,7 +3,7 @@ post:
     - Dictionnaries
   operationId: batchDictionaryEntries
   description: Send a batch of dictionary entries.
-  summary: Send a batch of dictionary entries.
+  summary: Batch dictionary entries.
   parameters:
     - $ref: 'common/parameters.yml#/DictionaryName'
   requestBody:

specs/search/paths/dictionaries/dictionarySettings.yml

@@ -31,8 +31,8 @@ put:
   tags:
     - Dictionnaries
   operationId: setDictionarySettings
-  description: Set dictionary settings.
-  summary: Set dictionary settings.
+  description: Set dictionaries settings.
+  summary: Set dictionaries settings.
   requestBody:
     required: true
     content:

specs/search/paths/dictionaries/getDictionaryLanguages.yml

@@ -3,7 +3,7 @@ get:
     - Dictionnaries
   operationId: getDictionaryLanguages
   description: List dictionaries supported per language.
-  summary: List dictionaries supported per language.
+  summary: List available languages.
   responses:
     '200':
       description: OK

specs/search/paths/dictionaries/searchDictionaryEntries.yml

@@ -3,7 +3,7 @@ post:
     - Dictionnaries
   operationId: searchDictionaryEntries
   description: Search the dictionary entries.
-  summary: Search the dictionary entries.
+  summary: Search a dictionary entries.
   parameters:
     - $ref: 'common/parameters.yml#/DictionaryName'
   requestBody:

specs/search/paths/keys/keys.yml

@@ -2,7 +2,7 @@ get:
   tags:
     - Api Keys
   operationId: listApiKeys
-  summary: Get the full list of API Keys.
+  summary: List API Keys.
   description: List API keys, along with their associated rights.
   responses:
     '200':
@@ -34,7 +34,7 @@ post:
   tags:
     - Api Keys
   operationId: addApiKey
-  summary: Create a new API key.
+  summary: Create an API key.
   description: Add a new API Key with specific permissions/restrictions.
   requestBody:
     required: true

specs/search/paths/multiclusters/batchAssignUserIds.yml

@@ -2,7 +2,7 @@ post:
   tags:
     - Clusters
   operationId: batchAssignUserIds
-  summary: Batch assign userIDs
+  summary: Batch assign userIDs.
   description: >
     Assign multiple userIDs to a cluster.
 

specs/search/paths/multiclusters/getTopUserIds.yml

@@ -2,7 +2,7 @@ get:
   tags:
     - Clusters
   operationId: getTopUserIds
-  summary: Get top userID
+  summary: Get top userID.
   description: >
     Get the top 10 userIDs with the highest number of records per cluster.
 

specs/search/paths/multiclusters/hasPendingMappings.yml

@@ -2,7 +2,7 @@ get:
   tags:
     - Clusters
   operationId: hasPendingMappings
-  summary: Has pending mappings
+  summary: Get migration status.
   description: >
     Get the status of your clusters' migrations or user creations.
 

specs/search/paths/multiclusters/listClusters.yml

@@ -2,7 +2,7 @@ get:
   tags:
     - Clusters
   operationId: listClusters
-  summary: List clusters
+  summary: List clusters.
   description: >
     List the clusters available in a multi-clusters setup for a single appID.
 

specs/search/paths/multiclusters/searchUserIds.yml

@@ -2,7 +2,7 @@ post:
   tags:
     - Clusters
   operationId: searchUserIds
-  summary: Search userID
+  summary: Search userID.
   description: >
     Search for userIDs.
 

specs/search/paths/multiclusters/userId.yml

@@ -2,7 +2,7 @@ get:
   tags:
     - Clusters
   operationId: getUserId
-  summary: Get userID
+  summary: Get userID.
   description: >
     Returns the userID data stored in the mapping.
 
@@ -31,7 +31,7 @@ delete:
   tags:
     - Clusters
   operationId: removeUserId
-  summary: Remove userID
+  summary: Remove userID.
   description: >
     Remove a userID and its associated data from the multi-clusters.
 

specs/search/paths/multiclusters/userIds.yml

@@ -2,7 +2,7 @@ post:
   tags:
     - Clusters
   operationId: assignUserId
-  summary: Assign or Move userID
+  summary: Assign or Move userID.
   description: >
     Assign or Move a userID to a cluster.
 
@@ -43,7 +43,7 @@ get:
   tags:
     - Clusters
   operationId: listUserIds
-  summary: List userIDs
+  summary: List userIDs.
   description: >
     List the userIDs assigned to a multi-clusters appID.
 

specs/search/paths/objects/batch.yml

@@ -2,8 +2,8 @@ post:
   tags:
     - Records
   operationId: batch
-  description: Performs multiple write operations in a single API call.
-  summary: Performs multiple write operations in a single API call.
+  description: Perform multiple write operations targetting one index, in a single API call.
+  summary: Batch operations to one index.
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
   requestBody:

specs/search/paths/objects/multipleBatch.yml

@@ -3,7 +3,7 @@ post:
     - Records
   operationId: multipleBatch
   description: Perform multiple write operations, potentially targeting multiple indices, in a single API call.
-  summary: Perform multiple write operations.
+  summary: Batch operations to many indices.
   requestBody:
     required: true
     content:

specs/search/paths/objects/object.yml

@@ -2,7 +2,7 @@ get:
   tags:
     - Records
   operationId: getObject
-  summary: Retrieve one object from the index.
+  summary: Retrieve an object.
   description: Retrieve one object from the index.
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
@@ -38,8 +38,11 @@ put:
   tags:
     - Records
   operationId: addOrUpdateObject
-  summary: Add or replace an object with a given object ID.
-  description: Add or replace an object with a given object ID. If the object does not exist, it will be created. If it already exists, it will be replaced.
+  summary: Add or replace an object.
+  description: |
+    Add or replace an object with a given object ID.
+    If the object does not exist, it will be created.
+    If it already exists, it will be replaced.
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
     - $ref: '../../../common/parameters.yml#/ObjectID'
@@ -66,7 +69,7 @@ delete:
   tags:
     - Records
   operationId: deleteObject
-  summary: Delete object.
+  summary: Delete an object.
   description: Delete an existing object.
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'

specs/search/paths/search/multipleQueries.yml

@@ -2,8 +2,8 @@ post:
   tags:
     - Search
   operationId: multipleQueries
-  description: Get search results for the given requests.
-  summary: Get search results for the given requests.
+  summary: Search many indices.
+  description: Perform a search operation targetting one or many indices.
   requestBody:
     required: true
     description: The `multipleQueries` requests and strategy.

specs/search/paths/search/search.yml

@@ -2,8 +2,8 @@ post:
   tags:
     - Search
   operationId: search
-  description: Get search results.
-  summary: Get search results.
+  summary: Search one index.
+  description: Perform a search operation targetting one specific index.
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
   requestBody:

specs/search/paths/search/searchForFacetValues.yml

@@ -2,7 +2,7 @@ post:
   tags:
     - Search
   operationId: searchForFacetValues
-  summary: Search for values of a given facet
+  summary: Search for values of a given facet.
   description: Search for values of a given facet, optionally restricting the returned values to those contained in objects matching other search criteria.
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'