## Summary
Publish OAS docs to bump.sh on merge to `main` or `8.x`
## To reviewers
* For now actual publication requires a manual step on bump.sh (so
things aren't going live immediately)
* Will get to serverless OAS docs next!
## Blockers
* Address vulnerable deps before merging:
https://github.com/bump-sh/cli/issues/583
---------
Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
## Summary
Updates the Open API docs make targets to use the correct bump.sh
dependency.
Unless I'm missing something obvious in my local configuration, `@npx
bump ...` uses [node-bump](https://www.npmjs.com/package/bump) not the
[bump.sh library](https://www.npmjs.com/package/bump-cli). I discovered
this while trying to run the make targets locally.
## Summary
Removing staging files for now. We can always revert this if it turns
out we need them.
## Reviewers
* I might be missing something in removing these, but right now I think
they are making commit noise and not really serving a purpose
* I moved the `final_merge` step to after the OAS snapshot capture
**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.
