OpenAPI SLO specification changes

x-pack/plugins/observability/docs/openapi/slo/Makefile

@@ -0,0 +1,20 @@
+.DEFAULT_GOAL := help
+
+.PHONY: validate
+validate: ## validate tree
+	@npx swagger-cli validate entrypoint.yaml
+
+.PHONY: bundle
+bundle: validate ## generate bundled.yaml and bundled.json
+	@npx @redocly/cli bundle entrypoint.yaml --output bundled.yaml --ext yaml
+	@npx @redocly/cli bundle entrypoint.yaml --output bundled.json --ext json
+	@$(MAKE) lint
+
+.PHONY: lint
+lint: ## lint bundled.json
+	@npx @redocly/cli lint bundled.json
+
+.PHONY: help
+help: ## you're looking at it
+	@awk 'BEGIN {FS = ":.*##"; printf "Usage: make \033[36m<target>\033[0m\n\nTargets:\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-10s\033[0m\t%s\n", $$1, $$2 }' $(MAKEFILE_LIST) | column -s$$'\t' -t
+

x-pack/plugins/observability/docs/openapi/slo/README.md

@@ -13,22 +13,21 @@ A guide about the OpenApi specification can be found at [https://swagger.io/docs
 
 ## Tools
 
-It is possible to validate the docs before bundling them with the following
+It is possible to manually validate the docs before bundling them with the following
 command in the `x-pack/plugins/observability/docs/openapi/slo` folder:
 
 ```bash
-  npx swagger-cli validate entrypoint.yaml
+make validate
 ```
 
-Then you can generate the `bundled` files by running the following commands:
+Then you can generate the `bundled` files by running the following command- this target will automatically validate inputs and lint the result:
 
 ```bash
-  npx @redocly/cli bundle entrypoint.yaml --output bundled.yaml --ext yaml
-  npx @redocly/cli bundle entrypoint.yaml --output bundled.json --ext json
+make bundle
 ```
 
-After generating the json bundle ensure that it is also valid by running the following command:
+To lint the generated bundle manually, run:
 
 ```bash
-   npx @redocly/cli lint bundled.json
+make lint
 ```