kibana

mirror of https://github.com/elastic/kibana.git synced 2025-04-22 17:04:01 -04:00

History

Maxim Palenov 7a2e7bef96 [HTTP/OAS] Merge OpenAPI specs by using `kbn-openapi-bundler` (#189262 ) 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.	2024-08-13 12:45:35 +02:00
..
merge_ess_oas.js	[HTTP/OAS] Merge OpenAPI specs by using `kbn-openapi-bundler` (#189262 )	2024-08-13 12:45:35 +02:00
merge_serverless_oas.js	[HTTP/OAS] Merge OpenAPI specs by using `kbn-openapi-bundler` (#189262 )	2024-08-13 12:45:35 +02:00

[HTTP/OAS] Merge OpenAPI specs by using kbn-openapi-bundler (#189262 )

**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.

2024-08-13 12:45:35 +02:00

merge_ess_oas.js [HTTP/OAS] Merge OpenAPI specs by using kbn-openapi-bundler (#189262 ) 2024-08-13 12:45:35 +02:00

merge_serverless_oas.js [HTTP/OAS] Merge OpenAPI specs by using kbn-openapi-bundler (#189262 ) 2024-08-13 12:45:35 +02:00