From f8856c722b341c58a52922fd72ce2168073e7843 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Wed, 11 Sep 2024 11:41:46 -0700 Subject: [PATCH] Add examples to both OpenAPI documents via overlays (#2882) --- .gitignore | 6 +- Makefile | 14 +++- .../elasticsearch-openapi-overlays.yaml | 21 ++++++ ...ticsearch-serverless-openapi-overlays.yaml | 72 ++----------------- ...elasticsearch-shared-example-overlays.yaml | 72 +++++++++++++++++++ 5 files changed, 114 insertions(+), 71 deletions(-) create mode 100644 docs/overlays/elasticsearch-openapi-overlays.yaml create mode 100644 docs/overlays/elasticsearch-shared-example-overlays.yaml diff --git a/.gitignore b/.gitignore index f873a572f0..68826241d8 100644 --- a/.gitignore +++ b/.gitignore @@ -66,5 +66,7 @@ output/schema/schema compiler/test/**/output/ # Temporary openAPI files -output/openapi/elasticsearch-serverless-openapi.tmp.json -output/openapi/elasticsearch-serverless-openapi.examples.json \ No newline at end of file +output/openapi/elasticsearch-serverless-openapi.tmp*.json +output/openapi/elasticsearch-serverless-openapi.examples.json +output/openapi/elasticsearch-openapi.tmp*.json +output/openapi/elasticsearch-openapi.examples.json \ No newline at end of file diff --git a/Makefile b/Makefile index 619952dfb2..e5a047d692 100644 --- a/Makefile +++ b/Makefile @@ -60,13 +60,21 @@ dump-routes: ## Create a new schema with all generics expanded contrib: | generate license-check spec-format-fix transform-to-openapi filter-for-serverless ## Pre contribution target overlay-docs: ## Apply overlays to OpenAPI documents - @npx bump overlay "output/openapi/elasticsearch-serverless-openapi.json" "docs/overlays/elasticsearch-serverless-openapi-overlays.yaml" > "output/openapi/elasticsearch-serverless-openapi.tmp.json" - @npx @redocly/cli bundle output/openapi/elasticsearch-serverless-openapi.tmp.json --ext json -o output/openapi/elasticsearch-serverless-openapi.examples.json - rm output/openapi/elasticsearch-serverless-openapi.tmp.json + @npx bump overlay "output/openapi/elasticsearch-serverless-openapi.json" "docs/overlays/elasticsearch-serverless-openapi-overlays.yaml" > "output/openapi/elasticsearch-serverless-openapi.tmp1.json" + @npx bump overlay "output/openapi/elasticsearch-serverless-openapi.tmp1.json" "docs/overlays/elasticsearch-shared-example-overlays.yaml" > "output/openapi/elasticsearch-serverless-openapi.tmp2.json" + @npx @redocly/cli bundle output/openapi/elasticsearch-serverless-openapi.tmp2.json --ext json -o output/openapi/elasticsearch-serverless-openapi.examples.json + @npx bump overlay "output/openapi/elasticsearch-openapi.json" "docs/overlays/elasticsearch-openapi-overlays.yaml" > "output/openapi/elasticsearch-openapi.tmp1.json" + @npx bump overlay "output/openapi/elasticsearch-openapi.tmp1.json" "docs/overlays/elasticsearch-shared-example-overlays.yaml" > "output/openapi/elasticsearch-openapi.tmp2.json" + @npx @redocly/cli bundle output/openapi/elasticsearch-openapi.tmp2.json --ext json -o output/openapi/elasticsearch-openapi.examples.json + rm output/openapi/elasticsearch-serverless-openapi.tmp*.json + rm output/openapi/elasticsearch-openapi.tmp*.json lint-docs: ## Lint the OpenAPI documents @npx @stoplight/spectral-cli lint output/openapi/*.json --ruleset .spectral.yaml +lint-docs-errs: ## Lint the OpenAPI documents and return only errors + @npx @stoplight/spectral-cli lint output/openapi/*.json --ruleset .spectral.yaml -D + lint-docs-serverless: ## Lint only the serverless OpenAPI document @npx @stoplight/spectral-cli lint output/openapi/elasticsearch-serverless-openapi.json --ruleset .spectral.yaml diff --git a/docs/overlays/elasticsearch-openapi-overlays.yaml b/docs/overlays/elasticsearch-openapi-overlays.yaml new file mode 100644 index 0000000000..6e33dbec30 --- /dev/null +++ b/docs/overlays/elasticsearch-openapi-overlays.yaml @@ -0,0 +1,21 @@ +# overlays.yaml +overlay: 1.0.0 +info: + title: Overlays for the Elasticsearch OpenAPI document + version: 0.0.1 +actions: + - target: '$.info' + description: Add a document description and feedback link + update: + title: Elasticsearch API + description: > + ## Documentation source and versions + + This documentation is derived from the `main` branch of the [elasticsearch-specification](https://github.com/elastic/elasticsearch-specification) repository. + It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/). + x-doc-license: + name: Attribution-NonCommercial-NoDerivatives 4.0 International + url: 'https://creativecommons.org/licenses/by-nc-nd/4.0/' + x-feedbackLink: + label: Feedback + url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+ diff --git a/docs/overlays/elasticsearch-serverless-openapi-overlays.yaml b/docs/overlays/elasticsearch-serverless-openapi-overlays.yaml index efb432341f..ff8a013400 100644 --- a/docs/overlays/elasticsearch-serverless-openapi-overlays.yaml +++ b/docs/overlays/elasticsearch-serverless-openapi-overlays.yaml @@ -7,6 +7,7 @@ actions: - target: '$.info' description: Add a document description and feedback link update: + title: Elasticsearch Serverless API description: > **Technical preview** This functionality is in technical preview and may be changed or removed in a future release. @@ -22,69 +23,8 @@ actions: x-feedbackLink: label: Feedback url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+ - - target: "$.components['requestBodies']['async_search.submit']" - description: "Add example for asynch search submit request" - update: - content: - application/json: - examples: - asyncSearchSubmitResponseExample1: - $ref: "../../specification/async_search/submit/AsyncSearchSubmitRequestExample1.json" - - target: "$.components['responses']['async_search.submit#200']" - description: "Add example for asynch search submit response" - update: - content: - application/json: - examples: - asyncSearchSubmitResponseExample1: - $ref: "../../specification/async_search/submit/AsyncSearchSubmitResponseExample1.json" - - target: "$.paths['/_transform/{transform_id}']['put']" - description: "Add examples for create transform operation" - update: - requestBody: - content: - application/json: - examples: - createTransformRequestExample1: - $ref: "../../specification/transform/put_transform/PutTransformRequestExample1.json" - createTransformRequestExample2: - $ref: "../../specification/transform/put_transform/PutTransformRequestExample2.json" - responses: - 200: - content: - application/json: - examples: - createTransformResponseExample1: - $ref: "../../specification/transform/put_transform/PutTransformResponseExample1.json" - - target: "$.components['requestBodies']['transform.preview_transform']" - description: "Add examples for preview transform operation" - update: - content: - application/json: - examples: - previewTransformRequestExample1: - $ref: "../../specification/transform/preview_transform/PreviewTransformRequestExample1.json" - - target: "$.components['reponses']['transform.preview_transform#200']" - description: "Add examples for preview transform operation" - update: - content: - application/json: - examples: - previewTransformResponseExample1: - $ref: "../../specification/transform/preview_transform/PreviewTransformResponseExample1.json" - - target: "$.paths['/_transform/{transform_id}/_update']['post']" - description: "Add examples for update transform operation" - update: - requestBody: - content: - application/json: - examples: - updateTransformRequestExample1: - $ref: "../../specification/transform/update_transform/UpdateTransformRequestExample1.json" - responses: - 200: - content: - application/json: - examples: - updateTransformResponseExample1: - $ref: "../../specification/transform/update_transform/UpdateTransformResponseExample1.json" \ No newline at end of file + # Temporarily mark all operations as beta + - target: "$.paths[*]['get','put','post','delete','options','head','patch','trace']" + description: Add x-beta + update: + x-beta: true \ No newline at end of file diff --git a/docs/overlays/elasticsearch-shared-example-overlays.yaml b/docs/overlays/elasticsearch-shared-example-overlays.yaml new file mode 100644 index 0000000000..033b8fb9b0 --- /dev/null +++ b/docs/overlays/elasticsearch-shared-example-overlays.yaml @@ -0,0 +1,72 @@ +# overlays.yaml +overlay: 1.0.0 +info: + title: Overlays for examples that apply to both Elasticsearcb and Elasticsearch Serverless OpenAPI documents + version: 0.0.1 +actions: + - target: "$.components['requestBodies']['async_search.submit']" + description: "Add example for asynch search submit request" + update: + content: + application/json: + examples: + asyncSearchSubmitResponseExample1: + $ref: "../../specification/async_search/submit/AsyncSearchSubmitRequestExample1.json" + - target: "$.components['responses']['async_search.submit#200']" + description: "Add example for asynch search submit response" + update: + content: + application/json: + examples: + asyncSearchSubmitResponseExample1: + $ref: "../../specification/async_search/submit/AsyncSearchSubmitResponseExample1.json" + - target: "$.paths['/_transform/{transform_id}']['put']" + description: "Add examples for create transform operation" + update: + requestBody: + content: + application/json: + examples: + createTransformRequestExample1: + $ref: "../../specification/transform/put_transform/PutTransformRequestExample1.json" + createTransformRequestExample2: + $ref: "../../specification/transform/put_transform/PutTransformRequestExample2.json" + responses: + 200: + content: + application/json: + examples: + createTransformResponseExample1: + $ref: "../../specification/transform/put_transform/PutTransformResponseExample1.json" + - target: "$.components['requestBodies']['transform.preview_transform']" + description: "Add examples for preview transform operation" + update: + content: + application/json: + examples: + previewTransformRequestExample1: + $ref: "../../specification/transform/preview_transform/PreviewTransformRequestExample1.json" + - target: "$.components['reponses']['transform.preview_transform#200']" + description: "Add examples for preview transform operation" + update: + content: + application/json: + examples: + previewTransformResponseExample1: + $ref: "../../specification/transform/preview_transform/PreviewTransformResponseExample1.json" + - target: "$.paths['/_transform/{transform_id}/_update']['post']" + description: "Add examples for update transform operation" + update: + requestBody: + content: + application/json: + examples: + updateTransformRequestExample1: + $ref: "../../specification/transform/update_transform/UpdateTransformRequestExample1.json" + responses: + 200: + content: + application/json: + examples: + updateTransformResponseExample1: + $ref: "../../specification/transform/update_transform/UpdateTransformResponseExample1.json" \ No newline at end of file