Add support for plain/text responses and fix GET /_cat. (#357)

Signed-off-by: dblock <[email protected]> Signed-off-by: Thomas Farr <[email protected]> Co-authored-by: Thomas Farr <[email protected]>
opensearch-project · Jun 24, 2024 · 7452827 · 7452827
1 parent 6083bf5
commit 7452827
Show file tree

Hide file tree

Showing 10 changed files with 53 additions and 49 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -43,9 +43,10 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Fixed GitHub pages ([#215](https://github.com/opensearch-project/opensearch-api-specification/pull/215))
 - Fixed missing 201 response in `/{index}/_doc/{id}` ([#331](https://github.com/opensearch-project/opensearch-api-specification/pull/331))
 - Fixed `SlowlogThresholds` ([#341](https://github.com/opensearch-project/opensearch-api-specification/pull/341))
-- Fixed `from_address` in notifications ([#341](https://github.com/opensearch-project/opensearch-api-specification/pull/341))
-- Fixed `pages_processed` in rollups ([#341](https://github.com/opensearch-project/opensearch-api-specification/pull/341))
+- Fixed `from_address` in `SmtpAccount` ([#341](https://github.com/opensearch-project/opensearch-api-specification/pull/341))
+- Fixed `pages_processed` in `/_plugins/_rollup` ([#341](https://github.com/opensearch-project/opensearch-api-specification/pull/341))
 - Fixed `_bulk` spec request and response types ([#355](https://github.com/opensearch-project/opensearch-api-specification/pull/355))
+- Fixed `text/plain` response in `/_cat` ([#357](https://github.com/opensearch-project/opensearch-api-specification/pull/357))
 
 ### Security
 

diff --git a/spec/namespaces/cat.yaml b/spec/namespaces/cat.yaml
@@ -12,9 +12,6 @@ paths:
       description: Returns help for the Cat APIs.
       externalDocs:
         url: https://opensearch.org/docs/latest/api-reference/cat/index/
-      parameters:
-        - $ref: '#/components/parameters/cat.help::query.help'
-        - $ref: '#/components/parameters/cat.help::query.s'
       responses:
         '200':
           $ref: '#/components/responses/cat.help@200'
@@ -842,11 +839,9 @@ components:
     cat.help@200:
       description: ''
       content:
-        application/json:
+        text/plain:
           schema:
-            type: array
-            items:
-              $ref: '../schemas/cat.help.yaml#/components/schemas/HelpRecord'
+            type: string
     cat.indices@200:
       description: ''
       content:
@@ -1432,25 +1427,6 @@ components:
         type: boolean
         default: false
         description: Verbose mode. Display column headers.
-    cat.help::query.help:
-      name: help
-      in: query
-      description: Return help information.
-      schema:
-        type: boolean
-        default: false
-        description: Return help information.
-    cat.help::query.s:
-      name: s
-      in: query
-      description: Comma-separated list of column names or column aliases to sort by.
-      style: form
-      schema:
-        type: array
-        items:
-          type: string
-        description: Comma-separated list of column names or column aliases to sort by.
-      explode: true
     cat.indices::path.index:
       in: path
       name: index

diff --git a/spec/schemas/cat.help.yaml b/spec/schemas/cat.help.yaml
diff --git a/tests/cat/index.yaml b/tests/cat/index.yaml
@@ -0,0 +1,11 @@
+$schema: ../../json_schemas/test_story.schema.yaml
+
+skip: false
+description: Test cat endpoints.
+chapters:
+  - synopsis: Cat with a json response.
+    path: /_cat
+    method: GET
+    response:
+      status: 200
+      content_type: text/plain
diff --git a/tools/src/merger/OpenApiMerger.ts b/tools/src/merger/OpenApiMerger.ts
@@ -69,7 +69,7 @@ export default class OpenApiMerger {
 
   // Redirect schema references in namespace files to local references in single-file spec.
   redirect_refs_in_namespace (obj: any): void {
-    const ref: string = obj.$ref
+    const ref: string = obj?.$ref
     if (ref?.startsWith('../schemas/')) { obj.$ref = ref.replace('../schemas/', '#/components/schemas/').replace('.yaml#/components/schemas/', ':') }
 
     for (const key in obj) {

diff --git a/tools/tests/tester/fixtures/evals/passed.yaml b/tools/tests/tester/fixtures/evals/passed.yaml
@@ -7,7 +7,7 @@ description: This story should pass.
 prologues: []
 
 chapters:
-  - title: This chapter should pass.
+  - title: This PUT /{index} chapter should pass.
     overall:
       result: PASSED
     request:
@@ -23,8 +23,22 @@ chapters:
         result: PASSED
       payload_schema:
         result: PASSED
+  - title: This GET /_cat chapter should pass.
+    overall:
+      result: PASSED
+    request:
+      parameters: {}
+      request_body:
+        result: PASSED
+    response:
+      status:
+        result: PASSED
+      payload_body:
+        result: PASSED
+      payload_schema:
+        result: PASSED
 
 epilogues:
   - title: DELETE /books
     overall:
-      result: PASSED
+      result: PASSED
diff --git a/...ester/fixtures/specs/indices_excerpt.yaml → .../tests/tester/fixtures/specs/excerpt.yaml b/...ester/fixtures/specs/indices_excerpt.yaml → .../tests/tester/fixtures/specs/excerpt.yaml
@@ -3,6 +3,15 @@ info:
   title: Test API
   version: 1.0.0
 paths:
+  /_cat:
+    get:
+      operationId: cat.help.0
+      x-operation-group: cat.help
+      x-version-added: '1.0'
+      description: Returns help for the Cat APIs.
+      responses:
+        '200':
+          $ref: '#/components/responses/cat.help@200'  
   /{index}:
     delete:
       operationId: indices.delete.0
@@ -59,6 +68,11 @@ components:
                 description: Optional mappings for the index.
             additionalProperties: false
   responses:
+    cat.help@200:
+      content:
+        text/plain:
+          schema:
+            type: string
     indices.delete@200:
       description: ''
       content:

diff --git a/tools/tests/tester/fixtures/stories/passed.yaml b/tools/tests/tester/fixtures/stories/passed.yaml
@@ -6,8 +6,11 @@ epilogues:
     method: DELETE
     status: [200, 404]
 chapters:
-  - synopsis: This chapter should pass.
+  - synopsis: This PUT /{index} chapter should pass.
     path: /{index}
     method: PUT
     parameters:
       index: books
+  - synopsis: This GET /_cat chapter should pass.
+    path: /_cat
+    method: GET
diff --git a/tools/tests/tester/integ/StoryEvaluator.test.ts b/tools/tests/tester/integ/StoryEvaluator.test.ts
@@ -9,7 +9,7 @@
 
 import { construct_tester_components, load_actual_evaluation, load_expected_evaluation } from '../helpers'
 
-const { story_evaluator } = construct_tester_components('tools/tests/tester/fixtures/specs/indices_excerpt.yaml')
+const { story_evaluator } = construct_tester_components('tools/tests/tester/fixtures/specs/excerpt.yaml')
 
 test('passed', async () => {
   const actual = await load_actual_evaluation(story_evaluator, 'passed')

diff --git a/tools/tests/tester/integ/TestRunner.test.ts b/tools/tests/tester/integ/TestRunner.test.ts
@@ -11,7 +11,7 @@ import { construct_tester_components, flatten_errors, load_expected_evaluation }
 import { type StoryEvaluation } from 'tester/types/eval.types'
 
 test('stories folder', async () => {
-  const { test_runner } = construct_tester_components('tools/tests/tester/fixtures/specs/indices_excerpt.yaml')
+  const { test_runner } = construct_tester_components('tools/tests/tester/fixtures/specs/excerpt.yaml')
   const result = await test_runner.run('tools/tests/tester/fixtures/stories')
 
   expect(result.failed).toBeTruthy()