Added text/plain responses to cat APIs.

CHANGELOG.md

@@ -28,6 +28,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added support for testing `application/x-ndjson` payloads ([#355](https://github.com/opensearch-project/opensearch-api-specification/pull/355))
 - Added SPECIFICATION_TESTING.md [#359](https://github.com/opensearch-project/opensearch-api-specification/pull/359)
 - Added StoryValidator to validate stories before running them ([#354](https://github.com/opensearch-project/opensearch-api-specification/issues/354))
+- Added support for `text/plain` responses in `_cat` APIs ([#360](https://github.com/opensearch-project/opensearch-api-specification/pull/360))
 
 ### Changed
 

package.json

@@ -37,6 +37,7 @@
     "@eslint/js": "^9.1.1",
     "@stylistic/eslint-plugin": "^2.3.0",
     "@types/jest": "^29.5.12",
+    "@types/qs": "^6.9.15",
     "@typescript-eslint/eslint-plugin": "^6.21.0",
     "ajv-errors": "^3.0.0",
     "eslint": "^8.57.0",
@@ -51,6 +52,7 @@
     "jest": "^29.7.0",
     "json-diff-ts": "^4.0.1",
     "json-schema-to-typescript": "^14.0.4",
+    "qs": "^6.12.1",
     "ts-jest": "^29.1.2"
   }
 }

spec/namespaces/cat.yaml

@@ -789,6 +789,8 @@ components:
     cat.aliases@200:
       description: ''
       content:
+        text/plain:
+          type: string
         application/json:
           schema:
             type: array
@@ -797,6 +799,8 @@ components:
     cat.all_pit_segments@200:
       description: ''
       content:
+        text/plain:
+          type: string
         application/json:
           schema:
             type: array
@@ -805,6 +809,8 @@ components:
     cat.allocation@200:
       description: ''
       content:
+        text/plain:
+          type: string
         application/json:
           schema:
             type: array
@@ -815,6 +821,8 @@ components:
     cat.count@200:
       description: ''
       content:
+        text/plain:
+          type: string
         application/json:
           schema:
             type: array
@@ -823,6 +831,8 @@ components:
     cat.fielddata@200:
       description: ''
       content:
+        text/plain:
+          type: string
         application/json:
           schema:
             type: array
@@ -831,6 +841,8 @@ components:
     cat.health@200:
       description: ''
       content:
+        text/plain:
+          type: string
         application/json:
           schema:
             type: array
@@ -845,6 +857,8 @@ components:
     cat.indices@200:
       description: ''
       content:
+        text/plain:
+          type: string
         application/json:
           schema:
             type: array
@@ -853,6 +867,8 @@ components:
     cat.master@200:
       description: ''
       content:
+        text/plain:
+          type: string
         application/json:
           schema:
             type: array
@@ -861,6 +877,8 @@ components:
     cat.nodeattrs@200:
       description: ''
       content:
+        text/plain:
+          type: string
         application/json:
           schema:
             type: array
@@ -869,6 +887,8 @@ components:
     cat.nodes@200:
       description: ''
       content:
+        text/plain:
+          type: string
         application/json:
           schema:
             type: array
@@ -877,6 +897,8 @@ components:
     cat.pending_tasks@200:
       description: ''
       content:
+        text/plain:
+          type: string
         application/json:
           schema:
             type: array
@@ -885,6 +907,8 @@ components:
     cat.pit_segments@200:
       description: ''
       content:
+        text/plain:
+          type: string
         application/json:
           schema:
             type: array
@@ -893,6 +917,8 @@ components:
     cat.plugins@200:
       description: ''
       content:
+        text/plain:
+          type: string
         application/json:
           schema:
             type: array
@@ -901,6 +927,8 @@ components:
     cat.recovery@200:
       description: ''
       content:
+        text/plain:
+          type: string
         application/json:
           schema:
             type: array
@@ -909,6 +937,8 @@ components:
     cat.repositories@200:
       description: ''
       content:
+        text/plain:
+          type: string
         application/json:
           schema:
             type: array
@@ -917,6 +947,8 @@ components:
     cat.segment_replication@200:
       description: ''
       content:
+        text/plain:
+          type: string
         application/json:
           schema:
             type: array
@@ -925,6 +957,8 @@ components:
     cat.segments@200:
       description: ''
       content:
+        text/plain:
+          type: string
         application/json:
           schema:
             type: array
@@ -933,6 +967,8 @@ components:
     cat.shards@200:
       description: ''
       content:
+        text/plain:
+          type: string
         application/json:
           schema:
             type: array
@@ -941,6 +977,8 @@ components:
     cat.snapshots@200:
       description: ''
       content:
+        text/plain:
+          type: string
         application/json:
           schema:
             type: array
@@ -949,6 +987,8 @@ components:
     cat.tasks@200:
       description: ''
       content:
+        text/plain:
+          type: string
         application/json:
           schema:
             type: array
@@ -957,6 +997,8 @@ components:
     cat.templates@200:
       description: ''
       content:
+        text/plain:
+          type: string
         application/json:
           schema:
             type: array
@@ -965,6 +1007,8 @@ components:
     cat.thread_pool@200:
       description: ''
       content:
+        text/plain:
+          type: string
         application/json:
           schema:
             type: array
@@ -1009,9 +1053,9 @@ components:
       in: query
       description: Return help information.
       schema:
+        description: Return help information.
         type: boolean
         default: false
-        description: Return help information.
     cat.aliases::query.local:
       name: local
       in: query

tests/cat/aliases.yaml

@@ -0,0 +1,19 @@
+$schema: ../../json_schemas/test_story.schema.yaml
+
+description: Test cat/aliases endpoints.
+chapters:
+  - synopsis: Cat with a text response.
+    path: /_cat/aliases
+    method: GET
+    response:
+      status: 200
+      content_type: text/plain
+  - synopsis: Cat with a json response.
+    path: /_cat/aliases
+    parameters:
+      format: json
+    method: GET
+    response:
+      status: 200
+      content_type: application/json
+      payload: []

tests/cat/health.yaml

@@ -0,0 +1,58 @@
+$schema: ../../json_schemas/test_story.schema.yaml
+
+description: Test cat/health endpoints.
+chapters:
+  - synopsis: Cat with a default text response.
+    method: GET
+    path: /_cat/health
+    response:
+      status: 200
+      content_type: text/plain
+  - synopsis: Cat with verbose output (v=true).
+    method: GET
+    path: /_cat/health
+    parameters:
+      v: true
+    response:
+      status: 200
+      content_type: text/plain
+  - synopsis: Cat with headers (h=header1,header2).
+    method: GET
+    path: /_cat/health
+    parameters:
+      h:
+        - status
+        - timestamp
+    response:
+      status: 200
+      content_type: text/plain
+  - synopsis: Cat displaying all available headers (help=true).
+    method: GET
+    path: /_cat/health
+    parameters:
+      help: true
+    response:
+      status: 200
+      content_type: text/plain
+  - synopsis: Cat with sorted results.
+    method: GET
+    path: /_cat/health
+    parameters:
+      s:
+        - status
+    response:
+      status: 200
+      content_type: text/plain
+  - synopsis: Cat with a json response.
+    method: GET
+    path: /_cat/health
+    parameters:
+      format: json
+    response:
+      status: 200
+      content_type: application/json
+      payload:
+        - node.total: '1'
+          status: yellow
+          node.data: '1'
+          discovered_cluster_manager: 'true'

tools/src/tester/ChapterReader.ts

@@ -12,6 +12,7 @@ import { type OpenSearchHttpClient } from '../OpenSearchHttpClient'
 import { type StoryOutputs } from './StoryOutputs'
 import { Logger } from 'Logger'
 import { to_json, to_ndjson } from '../helpers'
+import qs from 'qs'
 
 export default class ChapterReader {
   private readonly _client: OpenSearchHttpClient
@@ -37,7 +38,10 @@ export default class ChapterReader {
       method: chapter.method,
       headers: { 'Content-Type' : content_type },
       params,
-      data: request_data
+      data: request_data,
+      paramsSerializer: (params) => { // eslint-disable-line @typescript-eslint/naming-convention
+        return qs.stringify(params, { arrayFormat: 'comma' })
+      }
     }).then(r => {
       this.logger.info(`<= ${r.status} (${r.headers['content-type']}) | ${to_json(r.data)}`)
       response.status = r.status