diff --git a/CHANGELOG.md b/CHANGELOG.md index ceae883de..b0907b673 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index 643f4506d..76f19a1a4 100644 --- a/DEVELOPER_GUIDE.md +++ b/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): diff --git a/spec/namespaces/_core.yaml b/spec/namespaces/_core.yaml index 2e1aeb6cb..a992acaed 100644 --- a/spec/namespaces/_core.yaml +++ b/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: diff --git a/tests/info.yaml b/tests/_core/info.yaml similarity index 85% rename from tests/info.yaml rename to tests/_core/info.yaml index 367ce3cd9..5a8e14f07 100644 --- a/tests/info.yaml +++ b/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. diff --git a/tests/indices/_doc.yaml b/tests/indices/_doc.yaml new file mode 100644 index 000000000..b4789f0c7 --- /dev/null +++ b/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 diff --git a/tests/index.yaml b/tests/indices/index.yaml similarity index 97% rename from tests/index.yaml rename to tests/indices/index.yaml index a2e955ad6..3873b0230 100644 --- a/tests/index.yaml +++ b/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. diff --git a/tests/text_embedding_processor.yaml b/tests/ingest/pipeline.yaml similarity index 57% rename from tests/text_embedding_processor.yaml rename to tests/ingest/pipeline.yaml index ac1a98550..2408d79d3 100644 --- a/tests/text_embedding_processor.yaml +++ b/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: