Reorganized tests and added tests for _doc.

CHANGELOG.md

@@ -32,6 +32,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ### Fixed
 
 - 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))
 
 ### Security
 

DEVELOPER_GUIDE.md

@@ -9,6 +9,8 @@
     - [Global Parameters](#global-parameters)
     - [OpenAPI Extensions](#openapi-extensions)
   - [Writing Spec Tests](#writing-spec-tests)
+    - [Test Stories](#test-stories)
+    - [Organizing Tests](#organizing-tests)
     - [Running Spec Tests Locally](#running-spec-tests-locally)
   - [Tools](#tools)
     - [Setup](#setup)
@@ -150,12 +152,18 @@ This repository includes several OpenAPI Specification Extensions to fill in any
 
 ## Writing Spec Tests
 
-To assure the correctness of the spec, you must add tests for the spec in the [tests/](tests) directory. Each yaml file in the tests directory represents a test story that tests a collection of related operations. A test story has 3 main components:
+To assure the correctness of the spec, you must add tests for the spec in the [tests/](tests) directory.
+
+### Test Stories
+
+Each yaml file in the tests directory represents a test story that tests a collection of related operations.
+
+A test story has 3 main components:
 - prologues: These are the operations that are executed before the test story is run. They are used to set up the environment for the test story.
 - chapters: These are the operations that are being tested.
 - epilogues: These are the operations that are executed after the test story is run. They are used to clean up the environment after the test story.
 
-Below is the simplified version of the test story that tests the [index operations](tests/index.yaml):
+Below is the simplified version of the test story that tests the [index operations](tests/indices/index.yaml):
 ```yaml
 $schema: ../json_schemas/test_story.schema.yaml # The schema of the test story. Include this line so that your editor can validate the test story on the fly.
 
@@ -205,6 +213,10 @@ chapters:
 
 Check the [test_story JSON Schema](json_schemas/test_story.schema.yaml) for the complete structure of a test story.
 
+### Organizing Tests
+
+Tests are organized in folders that match [namespaces](spec/namespaces). For example, tests for APIs defined in [spec/namespaces/indices.yaml](spec/namespaces/indices.yaml) can be found in [tests/indices/index.yaml](tests/indices/index.yaml) (for `/{index}`), and [tests/indices/_doc.yaml](tests/indices/_doc.yaml) (for `/{index}/_doc`).
+
 ### Running Spec Tests Locally
 
 Set up an OpenSearch cluster with Docker using the default OPENSEARCH_PASSWORD (Recommended):

spec/namespaces/_core.yaml

@@ -1218,6 +1218,8 @@ paths:
       requestBody:
         $ref: '#/components/requestBodies/index'
       responses:
+        '201':
+          $ref: '#/components/responses/index@201'
         '200':
           $ref: '#/components/responses/index@200'
   /{index}/_doc/{id}:
@@ -1291,6 +1293,8 @@ paths:
       requestBody:
         $ref: '#/components/requestBodies/index'
       responses:
+        '201':
+          $ref: '#/components/responses/index@201'
         '200':
           $ref: '#/components/responses/index@200'
     put:
@@ -1317,6 +1321,8 @@ paths:
       requestBody:
         $ref: '#/components/requestBodies/index'
       responses:
+        '201':
+          $ref: '#/components/responses/index@201'
         '200':
           $ref: '#/components/responses/index@200'
     delete:
@@ -2875,6 +2881,12 @@ components:
         application/json:
           schema:
             $ref: '../schemas/_common.yaml#/components/schemas/WriteResponseBase'
+    index@201:
+      description: ''
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/_common.yaml#/components/schemas/WriteResponseBase'
     info@200:
       description: ''
       content:

tests/info.yaml → tests/_core/info.yaml

@@ -1,5 +1,5 @@
 
-$schema: ../json_schemas/test_story.schema.yaml
+$schema: ../../json_schemas/test_story.schema.yaml
 
 skip: false
 description: Test root endpoint.

tests/indices/_doc.yaml

@@ -0,0 +1,60 @@
+$schema: ../../json_schemas/test_story.schema.yaml
+
+skip: false
+description: Test inserting and retrieving a doc.
+epilogues:
+  - path: /movies
+    method: DELETE
+    status: [200, 404]
+chapters:
+  - synopsis: Create a document.
+    path: /{index}/_doc
+    method: POST
+    parameters:
+      index: movies
+    request_body:
+      payload:
+        title: Beauty and the Beast
+        year: 1991
+    response:
+      status: 201
+  - synopsis: Create a document.
+    path: /{index}/_doc/{id}
+    method: POST
+    parameters:
+      index: movies
+      id: '1'
+    request_body:
+      payload:
+        title: Beauty and the Beast (Id)
+        year: 1991
+    response:
+      status: 201
+  - synopsis: Update a document.
+    path: /{index}/_doc/{id}
+    method: PUT
+    parameters:
+      index: movies
+      id: '1'
+    request_body:
+      payload:
+        title: Beauty and the Beast (Updated)
+        year: 1991
+    response:
+      status: 200
+  - synopsis: Retrieve a document.
+    path: /{index}/_doc/{id}
+    method: GET
+    parameters:
+      index: movies
+      id: '1'
+    response:
+      status: 200
+  - synopsis: Delete a document.
+    path: /{index}/_doc/{id}
+    method: DELETE
+    parameters:
+      index: movies
+      id: '1'
+    response:
+      status: 200

tests/index.yaml → tests/indices/index.yaml

@@ -1,4 +1,4 @@
-$schema: ../json_schemas/test_story.schema.yaml
+$schema: ../../json_schemas/test_story.schema.yaml
 
 skip: false
 description: Test endpoints relevant the lifecycle of an index, from creation to deletion.

tests/text_embedding_processor.yaml → tests/ingest/pipeline.yaml

@@ -1,32 +1,31 @@
-$schema: ../json_schemas/test_story.schema.yaml
+$schema: ../../json_schemas/test_story.schema.yaml
 
 skip: false
 description: |
-  This test story checks that we can create an ingest pipeline with a text 
-  embedding processor
+  Test the creation of an ingest pipeline with a text embedding processor.
 epilogues:
   - path: /_ingest/pipeline/books_pipeline
     method: DELETE
     status: [200, 404]
 chapters:
-  - synopsis: Create ingest pipeline for text embedding
+  - synopsis: Create ingest pipeline for text embedding.
     path: /_ingest/pipeline/{id}
     method: PUT
     parameters:
       id: books_pipeline
     request_body:
       payload:
-        description: "Extracts text from field and embeds it"
+        description: Extracts text from field and embeds it.
         processors:
           - text_embedding:
-              model_id: "text-embedding-model"
+              model_id: text-embedding-model
               field_map:
-                text: "passage_embedding"
+                text: passage_embedding
     response:
       status: 200
       payload:
         acknowledged: true
-  - synopsis: Query created pipeline
+  - synopsis: Query created pipeline.
     path: /_ingest/pipeline/{id}
     method: GET
     parameters: