Add examples to both OpenAPI documents via overlays

.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
+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

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
 

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+

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"
+  # Temporarily mark all operations as beta
+  - target: "$.paths[*]['get','put','post','delete','options','head','patch','trace']"
+    description: Add x-beta
+    update:
+      x-beta: true

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"