Skip to content

Commit

Permalink
[8.16] [OpenAPI] Add redocly lint configuration (elastic#199360) (ela…
Browse files Browse the repository at this point in the history
…stic#199555)

# Backport

This will backport the following commits from `main` to `8.16`:
- [[OpenAPI] Add redocly lint configuration
(elastic#199360)](elastic#199360)

<!--- Backport version: 8.9.8 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT [{"author":{"name":"Lisa
Cawley","email":"[email protected]"},"sourceCommit":{"committedDate":"2024-11-08T20:07:55Z","message":"[OpenAPI]
Add redocly lint configuration
(elastic#199360)","sha":"907d19b7b82598ab070901f772323b71b583bc65","branchLabelMapping":{"^v9.0.0$":"main","^v8.17.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","v9.0.0","Feature:OAS","v8.16.0","backport:version","v8.17.0"],"number":199360,"url":"https://github.com/elastic/kibana/pull/199360","mergeCommit":{"message":"[OpenAPI]
Add redocly lint configuration
(elastic#199360)","sha":"907d19b7b82598ab070901f772323b71b583bc65"}},"sourceBranch":"main","suggestedTargetBranches":["8.16","8.x"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","labelRegex":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/199360","number":199360,"mergeCommit":{"message":"[OpenAPI]
Add redocly lint configuration
(elastic#199360)","sha":"907d19b7b82598ab070901f772323b71b583bc65"}},{"branch":"8.16","label":"v8.16.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.x","label":"v8.17.0","labelRegex":"^v8.17.0$","isSourceBranch":false,"state":"NOT_CREATED"}]}]
BACKPORT-->

NOTE: I've also removed the serverless commands from the makefile, since
they're not relevant to this branch.

This PR will encounter CI failures until
elastic#199571 is merged.
  • Loading branch information
lcawl authored Nov 9, 2024
1 parent 02079f6 commit 41a7e61
Show file tree
Hide file tree
Showing 4 changed files with 59 additions and 29 deletions.
3 changes: 1 addition & 2 deletions oas_docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,8 +45,7 @@ Besides the scripts in the `oas_docs/scripts` folder, there is an `oas_docs/make
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `api-docs` | Builds ESS Kibana OpenAPI bundle |
| `api-docs-serverless` | Builds Serverless Kibana OpenAPI bundle |
| `api-docs-lint` | Lints built result bundles |
| `api-docs-lint-errs` | Lints built result bundles for errors |
| `api-docs-lint` | Lints built result bundles |
| `api-docs-preview` | Generates (ESS + Serverless) Kibana OpenAPI bundles preview |
| `api-docs-overlay` | Applies [overlays](https://docs.bump.sh/help/specification-support/overlays/) from `overlays` folder to the Kibana OpenAPI bundles and generate `*.new.yaml` files. Overlays help to fine tune the result bundles. |
| `api-docs-overlay-preview` | Generates a preview for bundles produced by `api-docs-overlay` |
File renamed without changes.
52 changes: 52 additions & 0 deletions oas_docs/linters/redocly.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
extends:
- recommended
rules:
# Built-in rules
# Descriptions
parameter-description: warn
tag-description: warn
operation-description: off
# Document info
info-contact: warn
info-license: warn
# Examples
no-invalid-media-type-examples:
severity: warn
allowAdditionalProperties: false
no-invalid-schema-examples:
severity: warn
allowAdditionalProperties: false
# Operations
operation-operationId: error
operation-operationId-unique: error
operation-operationId-url-safe: warn
operation-summary: warn
# Parameters
path-parameters-defined: warn
# Paths
no-ambiguous-paths: warn
no-identical-paths: error
path-excludes-patterns:
severity: error
patterns:
- ^\/internal
# Responses
operation-4xx-response: off
operation-2xx-response: off
# Schema
spec: off
spec-strict-refs: off
# Tags
operation-tag-defined: off
tags-alphabetical: off
operation-singular-tag: off
# Custom rules
rule/operation-summary-length:
subject:
type: Operation
property: summary
message: Operation summary must have a minimum of 5 and maximum of 45 characters
severity: warn
assertions:
maxLength: 45
minLength: 5
33 changes: 6 additions & 27 deletions oas_docs/makefile
Original file line number Diff line number Diff line change
Expand Up @@ -14,58 +14,37 @@
# permission is obtained from Elasticsearch B.V.

.PHONY: api-docs
api-docs: ## Generate Serverless and ESS Kibana OpenAPI bundles with kbn-openapi-bundler
@node scripts/merge_serverless_oas.js
api-docs: ## Generate ESS Kibana OpenAPI bundles with kbn-openapi-bundler
@node scripts/merge_ess_oas.js

.PHONY: api-docs-stateful
api-docs-stateful: ## Generate only kibana.yaml
@node scripts/merge_ess_oas.js

.PHONY: api-docs-serverless
api-docs-serverless: ## Generate only kibana.serverless.yaml
@node scripts/merge_serverless_oas.js


.PHONY: api-docs-lint
api-docs-lint: ## Run spectral API docs linter
@npx @stoplight/spectral-cli lint "output/*.yaml" --ruleset ".spectral.yaml"

.PHONY: api-docs-lint-errs
api-docs-lint-errs: ## Run spectral API docs linter and return only errors
@npx @stoplight/spectral-cli lint "output/*.yaml" --ruleset ".spectral.yaml" -D
api-docs-lint: ## Run redocly API docs linter
@npx @redocly/cli lint "output/*.yaml" --config "linters/redocly.yaml" --format stylish --max-problems 500

.PHONY: api-docs-lint-stateful
api-docs-lint-stateful: ## Run spectral API docs linter on kibana.yaml
@npx @stoplight/spectral-cli lint "output/kibana.yaml" --ruleset ".spectral.yaml"

.PHONY: api-docs-lint-serverless
api-docs-lint-serverless: ## Run spectral API docs linter on kibana.serverless.yaml
@npx @stoplight/spectral-cli lint "output/kibana.serverless.yaml" --ruleset ".spectral.yaml"
api-docs-lint-stateful: ## Run redocly API docs linter on kibana.yaml
@npx @redocly/cli lint "output/kibana.yaml" --config "linters/redocly.yaml" --format stylish --max-problems 500

.PHONY: api-docs-overlay
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.serverless.tmp3.yaml" "overlays/kibana.overlays.shared.yaml" > "output/kibana.serverless.tmp4.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 bump overlay "output/kibana.tmp2.yaml" "overlays/connectors.overlays.yaml" > "output/kibana.tmp3.yaml"
@npx bump overlay "output/kibana.tmp3.yaml" "overlays/kibana.overlays.shared.yaml" > "output/kibana.tmp4.yaml"
@npx @redocly/cli bundle output/kibana.serverless.tmp4.yaml --ext yaml -o output/kibana.serverless.new.yaml
@npx @redocly/cli bundle output/kibana.tmp4.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)
Expand Down

0 comments on commit 41a7e61

Please sign in to comment.