Add transform API via overlay

Author: lcawl

Makefile

@@ -58,6 +58,17 @@ contrib: | generate license-check spec-format-fix transform-to-openapi ## Pre co
 bump:
 	@echo ">> bumping..."
 	.ci/bump.sh
+	
+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
+
+lint-docs: ## Lint the OpenAPI documents
+	@npx @stoplight/spectral-cli lint output/openapi/*.json --ruleset .spectral.yaml
+
+lint-docs-serverless: ## Lint only the serverless OpenAPI document
+	@npx @stoplight/spectral-cli lint output/openapi/elasticsearch-serverless-openapi.json --ruleset .spectral.yaml
 
 help:  ## Display help
 	@awk 'BEGIN {FS = ":.*##"; printf "Usage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)

docs/overlays/elasticsearch-serverless-openapi-overlays.yaml

@@ -0,0 +1,33 @@
+# overlays.yaml
+overlay: 1.0.0
+info:
+  title: Overlays for the Elasticsearch Serverless OpenAPI document
+  version: 0.0.1
+actions:
+  - target: '$.info'
+    description: Add a document description
+    update:
+      description: >
+        **Technical preview**  
+        This functionality is in technical preview and may be changed or removed in a future release.
+        Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
+  - target: "$.paths['/_transform/{transform_id}']['put']"
+    description: "Update create transform operation"
+    update: 
+      requestBody: 
+        content: 
+          application/json: 
+            examples: 
+              createTransformRequestExample1: 
+                $ref: "../../specification/transform/put_transform/examples/request/PutTransformRequestExample1.json"
+              createTransformRequestExample2:
+                $ref: "../../specification/transform/put_transform/examples/request/PutTransformRequestExample2.json"
+      responses:
+        200:
+          content:
+            application/json:
+              examples:
+                createTransformResponseExample1:
+                  $ref: "../../specification/transform/put_transform/examples/200_response/PutTransformResponseExample1.json"
+               
+