# Backport
This will backport the following commits from `main` to `8.16`:
- [[OAS] Publish OAS bundles to bump.sh
(#197482)](https://github.com/elastic/kibana/pull/197482)
<!--- Backport version: 8.9.8 -->
### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)
<!--BACKPORT [{"author":{"name":"Jean-Louis
Leysens","email":"jeanlouis.leysens@elastic.co"},"sourceCommit":{"committedDate":"2024-11-14T08:15:47Z","message":"[OAS]
Publish OAS bundles to bump.sh (#197482)\n\n## Summary\r\n\r\nPublish
OAS docs to bump.sh on merge to `main` or `8.x`\r\n\r\n## To
reviewers\r\n* For now actual publication requires a manual step on
bump.sh (so\r\nthings aren't going live immediately)\r\n* Will get to
serverless OAS docs next!\r\n\r\n## Blockers\r\n\r\n* Address vulnerable
deps before
merging:\r\nhttps://github.com/bump-sh/cli/issues/583\r\n\r\n---------\r\n\r\nCo-authored-by:
kibanamachine
<42973632+kibanamachine@users.noreply.github.com>","sha":"8278b0650ad4bb35e1a702889afad1f96eae2cd6","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":197482,"url":"https://github.com/elastic/kibana/pull/197482","mergeCommit":{"message":"[OAS]
Publish OAS bundles to bump.sh (#197482)\n\n## Summary\r\n\r\nPublish
OAS docs to bump.sh on merge to `main` or `8.x`\r\n\r\n## To
reviewers\r\n* For now actual publication requires a manual step on
bump.sh (so\r\nthings aren't going live immediately)\r\n* Will get to
serverless OAS docs next!\r\n\r\n## Blockers\r\n\r\n* Address vulnerable
deps before
merging:\r\nhttps://github.com/bump-sh/cli/issues/583\r\n\r\n---------\r\n\r\nCo-authored-by:
kibanamachine
<42973632+kibanamachine@users.noreply.github.com>","sha":"8278b0650ad4bb35e1a702889afad1f96eae2cd6"}},"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/197482","number":197482,"mergeCommit":{"message":"[OAS]
Publish OAS bundles to bump.sh (#197482)\n\n## Summary\r\n\r\nPublish
OAS docs to bump.sh on merge to `main` or `8.x`\r\n\r\n## To
reviewers\r\n* For now actual publication requires a manual step on
bump.sh (so\r\nthings aren't going live immediately)\r\n* Will get to
serverless OAS docs next!\r\n\r\n## Blockers\r\n\r\n* Address vulnerable
deps before
merging:\r\nhttps://github.com/bump-sh/cli/issues/583\r\n\r\n---------\r\n\r\nCo-authored-by:
kibanamachine
<42973632+kibanamachine@users.noreply.github.com>","sha":"8278b0650ad4bb35e1a702889afad1f96eae2cd6"}},{"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-->
---------
Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>
Co-authored-by: Lisa Cawley <lcawley@elastic.co>
# Backport
This will backport the following commits from `main` to `8.16`:
- [[OAS][Docs] Use correct bump dependency in makefile
(#199876)](https://github.com/elastic/kibana/pull/199876)
<!--- Backport version: 8.9.8 -->
### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)
<!--BACKPORT [{"author":{"name":"Nick
Peihl","email":"nick.peihl@elastic.co"},"sourceCommit":{"committedDate":"2024-11-13T13:13:54Z","message":"[OAS][Docs]
Use correct bump dependency in makefile (#199876)\n\n##
Summary\r\n\r\nUpdates the Open API docs make targets to use the correct
bump.sh\r\ndependency.\r\n\r\nUnless I'm missing something obvious in my
local configuration, `@npx\r\nbump ...` uses
[node-bump](https://www.npmjs.com/package/bump) not the\r\n[bump.sh
library](https://www.npmjs.com/package/bump-cli). I discovered\r\nthis
while trying to run the make targets
locally.","sha":"fcc939281d504a368f96c89d302c860ccb7c4dfe","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","backport:version","v8.17.0","v8.16.1"],"number":199876,"url":"https://github.com/elastic/kibana/pull/199876","mergeCommit":{"message":"[OAS][Docs]
Use correct bump dependency in makefile (#199876)\n\n##
Summary\r\n\r\nUpdates the Open API docs make targets to use the correct
bump.sh\r\ndependency.\r\n\r\nUnless I'm missing something obvious in my
local configuration, `@npx\r\nbump ...` uses
[node-bump](https://www.npmjs.com/package/bump) not the\r\n[bump.sh
library](https://www.npmjs.com/package/bump-cli). I discovered\r\nthis
while trying to run the make targets
locally.","sha":"fcc939281d504a368f96c89d302c860ccb7c4dfe"}},"sourceBranch":"main","suggestedTargetBranches":["8.x","8.16"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","labelRegex":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/199876","number":199876,"mergeCommit":{"message":"[OAS][Docs]
Use correct bump dependency in makefile (#199876)\n\n##
Summary\r\n\r\nUpdates the Open API docs make targets to use the correct
bump.sh\r\ndependency.\r\n\r\nUnless I'm missing something obvious in my
local configuration, `@npx\r\nbump ...` uses
[node-bump](https://www.npmjs.com/package/bump) not the\r\n[bump.sh
library](https://www.npmjs.com/package/bump-cli). I discovered\r\nthis
while trying to run the make targets
locally.","sha":"fcc939281d504a368f96c89d302c860ccb7c4dfe"}},{"branch":"8.x","label":"v8.17.0","labelRegex":"^v8.17.0$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.16","label":"v8.16.1","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"}]}]
BACKPORT-->
# Backport
This will backport the following commits from `main` to `8.16`:
- [[OpenAPI] Add redocly lint configuration
(#199360)](https://github.com/elastic/kibana/pull/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":"lcawley@elastic.co"},"sourceCommit":{"committedDate":"2024-11-08T20:07:55Z","message":"[OpenAPI]
Add redocly lint configuration
(#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
(#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
(#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
https://github.com/elastic/kibana/pull/199571 is merged.
# Backport
This will backport the following commits from `main` to `8.16`:
- [OAS] Removing staging files (#197455) (77ce0fcb)
<!--- Backport version: 8.9.8 -->
### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)
<!--BACKPORT [{"author":{"name":"Jean-Louis
Leysens","email":"jeanlouis.leysens@elastic.co"},"sourceCommit":{"committedDate":"2024-10-24T14:52:13Z","message":"[OAS]
Removing staging files (#197455)\n\n## Summary\r\n\r\nRemoving staging
files for now. We can always revert this if it turns\r\nout we need
them.\r\n\r\n## Reviewers\r\n\r\n* I might be missing something in
removing these, but right now I think\r\nthey are making commit noise
and not really serving a purpose\r\n* I moved the `final_merge` step to
after the OAS snapshot
capture","sha":"77ce0fcbcf18805d2ae1ac2d21a449c03deec022"},"sourceBranch":"main","suggestedTargetBranches":[],"targetPullRequestStates":[]}]
BACKPORT-->
Co-authored-by: Jean-Louis Leysens <jeanlouis.leysens@elastic.co>
# Backport
This will backport the following commits from `main` to `8.16`:
- [[DOCS][OpenAPI] Add descriptions, examples, tags, responses for space
APIs (#195333)](https://github.com/elastic/kibana/pull/195333)
<!--- Backport version: 9.4.3 -->
### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)
<!--BACKPORT [{"author":{"name":"Lisa
Cawley","email":"lcawley@elastic.co"},"sourceCommit":{"committedDate":"2024-10-18T19:03:06Z","message":"[DOCS][OpenAPI]
Add descriptions, examples, tags, responses for space APIs
(#195333)\n\nCo-authored-by: Elena Shostak
<165678770+elena-shostak@users.noreply.github.com>","sha":"2656e5a4ff79277c9a370ee24d6692ccb1d3142c","branchLabelMapping":{"^v9.0.0$":"main","^v8.17.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Feature:Security/Spaces","release_note:skip","v9.0.0","docs","v8.16.0","backport:version","v8.17.0"],"title":"[DOCS][OpenAPI]
Add descriptions, examples, tags, responses for space
APIs","number":195333,"url":"https://github.com/elastic/kibana/pull/195333","mergeCommit":{"message":"[DOCS][OpenAPI]
Add descriptions, examples, tags, responses for space APIs
(#195333)\n\nCo-authored-by: Elena Shostak
<165678770+elena-shostak@users.noreply.github.com>","sha":"2656e5a4ff79277c9a370ee24d6692ccb1d3142c"}},"sourceBranch":"main","suggestedTargetBranches":["8.16","8.x"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","branchLabelMappingKey":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/195333","number":195333,"mergeCommit":{"message":"[DOCS][OpenAPI]
Add descriptions, examples, tags, responses for space APIs
(#195333)\n\nCo-authored-by: Elena Shostak
<165678770+elena-shostak@users.noreply.github.com>","sha":"2656e5a4ff79277c9a370ee24d6692ccb1d3142c"}},{"branch":"8.16","label":"v8.16.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.x","label":"v8.17.0","branchLabelMappingKey":"^v8.17.0$","isSourceBranch":false,"state":"NOT_CREATED"}]}]
BACKPORT-->
Co-authored-by: Lisa Cawley <lcawley@elastic.co>
**Addresses:** https://github.com/elastic/kibana/issues/186356
**Relates to:** https://github.com/elastic/kibana/issues/184428
## Summary
This PR adds a merging JS script based on the utility implemented in https://github.com/elastic/kibana/issues/186356. Resulted OpenAPI bundle as committed in `oas_docs/output/kibana.serverless.bundled.yaml`.
## Details
https://github.com/elastic/kibana/pull/188110 implements and exposes `merge` utility design to merge source OpenAPI specs without processing. It's has only a programmatic API. To merge OpenAPI specs it's required to add a JS script like below
```js
const { merge } = require('@kbn/openapi-bundler');
(async () => {
await merge({
sourceGlobs: [/* a list of source globs goes here */],
outputFilePath: 'path/to/the/output/file.yaml',
});
})();
```
The JS script added in this PR includes source OpenAPI specs presented in `oas_docs/makefile` plus Security Solution OpenAPI specs based on https://github.com/elastic/kibana/issues/184428.
**To run** the script use the following command from Kibana root folder
```bash
node ./oas_docs/scripts/merge_serverless_oas.js
```
## Known linting issues with Security Solution OpenAPI specs
Running Spectral OpenAPI linter on the result bundle shows a number of errors caused by `no-$ref-siblings` rule. This caused by the current code generator implementation which requires `default` property to be set next to `$ref` though it's not correct for OpenAPI `3.0.3` while it's allowed in `3.1`. It seems that Bump.sh handles such cases properly though by properly showing a default value.
We need to analyze the problem and decide if/when we should fix it.
The rest of warnings look fixable and will be addressed in the next stage after setting up linter rules.
## Next steps
Since `@kbn/openapi-bundler` package is tailored specifically for Kibana it should replace Redocly currently used to merge OpenAPI specs. It also means `oas_docs/makefile` should be superseded by JS script(s) using `merge` utility form `@kbn/openapi-bundler` package.
`@kbn/openapi-bundler` SHOULD NOT replace OpenAPI linters since it doesn't perform thorough linting. It's good if we continue adopting `spectral-cli` for linting purposes.
