Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[OAS] Remove elastic-api-version from stateful spec #197968

Closed
wants to merge 17 commits into from
Closed

[OAS] Remove elastic-api-version from stateful spec #197968

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
30040c9
"make api-docs" do everything incl overlays and remove some of the do…
jloleysens Oct 28, 2024
e7b575d
no extension
jloleysens Oct 28, 2024
4fec6f3
updated file output
jloleysens Oct 28, 2024
068ca44
added echoes when rendering previews
jloleysens Oct 28, 2024
2996047
npm install
jloleysens Oct 28, 2024
9978403
package.json to oas_docs
jloleysens Oct 28, 2024
6a97460
move sed
jloleysens Oct 28, 2024
d11c73d
[CI] Auto-commit changed files from 'make api-docs'
kibanamachine Oct 28, 2024
82172c5
cd and log
jloleysens Oct 29, 2024
b9e394f
Merge branch 'main' into oas/remove-elastic-api-from-stateful-doc
jloleysens Oct 29, 2024
b6dd030
[CI] Auto-commit changed files from 'make api-docs'
kibanamachine Oct 29, 2024
dca423d
Merge branch 'main' into oas/remove-elastic-api-from-stateful-doc
jloleysens Oct 29, 2024
b91fd9d
Merge branch 'main' into oas/remove-elastic-api-from-stateful-doc
jloleysens Oct 30, 2024
7656280
Merge branch 'main' into oas/remove-elastic-api-from-stateful-doc
jloleysens Oct 31, 2024
c180177
[CI] Auto-commit changed files from 'make api-docs'
kibanamachine Oct 31, 2024
d4709cb
Update capture_oas_snapshot.sh
jloleysens Nov 5, 2024
91cfe8f
Update capture_oas_snapshot.sh
jloleysens Nov 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 2 additions & 4 deletions oas_docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,14 +39,12 @@ The `oas_docs/output` folder contains the final resulting Kibana OpenAPI bundles

## Bundling commands

Besides the scripts in the `oas_docs/scripts` folder, there is an `oas_docs/makefile` to simplify the workflow. The following makefile targets are available:
Use `make help` to get a list of all commands. The following are the most useful:

| Command | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `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-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` |
| `api-docs-overlay` | Applies [overlays](https://docs.bump.sh/help/specification-support/overlays/) from `overlays` folder to the Kibana OpenAPI bundles. |
27 changes: 14 additions & 13 deletions oas_docs/makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,16 +14,21 @@
# permission is obtained from Elasticsearch B.V.

.PHONY: api-docs
api-docs: ## Generate Serverless and ESS Kibana OpenAPI bundles with kbn-openapi-bundler
api-docs: ## Generate Serverless and ESS Kibana OpenAPI bundles
$(MAKE) merge-api-docs
$(MAKE) api-docs-overlay

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

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

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

.PHONY: api-docs-lint
Expand All @@ -43,7 +48,7 @@ api-docs-lint-serverless: ## Run spectral API docs linter on kibana.serverless.y
@npx @stoplight/spectral-cli lint "output/kibana.serverless.yaml" --ruleset ".spectral.yaml"

.PHONY: api-docs-overlay
api-docs-overlay: ## Run spectral API docs linter on kibana.serverless.yaml
api-docs-overlay: ## Apply all overlays
@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"
Expand All @@ -52,8 +57,9 @@ api-docs-overlay: ## Run spectral API docs linter on kibana.serverless.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
@npx @redocly/cli bundle output/kibana.serverless.tmp4.yaml --ext yaml -o output/kibana.serverless.yaml
@npx @redocly/cli bundle output/kibana.tmp4.yaml --ext yaml -o output/kibana.yaml
@sed -i '' -e 's/; Elastic-Api-Version=[0-9]\{4\}-[0-9]\{2\}-[0-9]\{2\}//g' output/kibana.yaml
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lukeelmers this is where we remove the Elastic-Api-Version from the stateful bundles. For now I think this should be OK as, in future, we might choose to introduce them there more formally.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks! does it need to be there in serverless too... it feels like we could remove it in both places, right? (since it looks like this is the one that's in the content-type which afaik nobody needs to actually include)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

my concern for stateful is that it will be confusing as we have not formally/publicly explained how the dual date/stack versioning works there.

my concern for serverless is that it is just redundant and also a bit confusing since content-type does not dictate api version (unless I missed something)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

my concern for serverless is that it is just redundant and also a bit confusing since content-type does not dictate api version (unless I missed something)

My understanding is it is intended to be used for grouping our serverless versions. Until that strategy changes from docs side I don't think we should remove it for now.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Relates to elastic/docs-content#142 As soon as we start having multiple valid in-support elastic-api-version values in stateful or serverless, we'll need to be able to differentiate their impact on the requests and responses.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... we have not formally/publicly explained how the dual date/stack versioning works there.

Whenever we're ready to document that, it can be added to the API docs in a topic similar to https://www.elastic.co/docs/api/doc/kibana/topic/topic-kibana-spaces, which we add via

kibana/oas_docs/overlays/kibana.overlays.yaml

Line 11 in d601e23

x-topics:

rm output/kibana.tmp*.yaml
rm output/kibana.serverless.tmp*.yaml

Expand All @@ -62,11 +68,6 @@ api-docs-preview: ## Generate a preview for kibana.yaml and kibana.serverless.ya
@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> --------------
Expand Down
Loading