## Summary
We want to allow rule executors to report warnings back to the framework
and have them show up in the stack management UI. We currently have a
mechanism for this that is used by detection rules but they handle how
to show the warning in their custom UI so the warning does not appear in
the stack management UI. This PR adds a new value to the allow list of
"warning reasons". This should not warrant a schema version bump because
it is a new value for an existing enum but we need to do an intermediate
release so the new schema is recognized before we start setting it
anywhere. This PR is just for schema changes. PR that uses these schema
changes can be found here: https://github.com/elastic/kibana/pull/189312
---------
Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>
## Summary
Includes alerting rule APIs in our OAS snapshots.
## How to test
Using bump CLI you can preview the output:
```sh
bump preview ./oas_docs/bundle.json
# or
bump preview ./oas_docs/bundle.serverless.json
```
---------
Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
**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.
## Summary
* Adds the ability to exclude a response schema when declaring route
schemas
* Adds the ability to provide a description of a the response
See code comments for more info.
## Example
You can declare a response with no validation to imply an empty object
in OAS
```
router.versioned.post({ version: '2023-10-31', access: 'public', path: '...' })
.addVersion({
validation: {
responses: {
201: { description: 'Resource created!' }
}
}
}, () => {})
```
Will result in
```jsonc
{
//...
201: { description: 'Resource created!' }
//...
}
```
## Risks
No notable risks
## Summary
Close https://github.com/elastic/kibana/issues/184719
Adds the ability to capture OAS for `serverless` build flavor in
addition to `traditional`. By default the CLI will run for both, but
this can be controlled by passing in one of two new flags:
`--no-serverless` or `--no-traditional`.
See `oas_docs/bundle.serverless.json` for output.
---------
Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
## Summary
Per [the OAS docs](https://swagger.io/specification/), they have an info
object with a `summary` and `description` field. This PR refactors the
existing router `description` field to to OAS `summary` (that is how it
has been used) and introduces a "new" `description` field that will be
used for the longer form descriptions.
## Resources
* https://swagger.io/specification/
---------
Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
Co-authored-by: lcawl <lcawley@elastic.co>
Close https://github.com/elastic/kibana/issues/181992
## Summary
First iteration of a CLI to capture an OAS snapshot.
## How to test
Run `node ./scripts/capture_oas_snapshot.js --update --include-path
/api/status` and see result in `oas_docs/bundle.json`.
If you have the [bump CLI](https://www.npmjs.com/package/bump-cli)
installed you can preview the hosted output with `bump preview
./oas_docs/bundle.json`
## Notes
* Added ability to filter by `version`, `access` (public/internal) and
excluding paths explicitly to the OAS generation lib
* Follows the same general pattern as our other "capture" CLIs like
`packages/kbn-check-mappings-update-cli`
* Result includes only `/api/status` for now, waiting for other paths to
add missing parts
---------
Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
