## Summary
Closes https://github.com/elastic/kibana/issues/184685
**Release notes**: These schema changes shouldn't be breaking, but there
were some incorrect/missing response schemas in the old openapi spec.
For example the API `POST /api/fleet/agents/{agentId}/actions` response
was incorrectly documented:
https://petstore.swagger.io/?url=https://raw.githubusercontent.com/elastic/kibana/main/x-pack/plugins/fleet/common/openapi/bundled.json#/Elastic%20Agent%20actions/new-agent-action
```
{
"body": [
0
],
"statusCode": 0,
"headers": "string"
}
```
Fixed here:
31f8cfd6ef/oas_docs/bundle.json#/Elastic%20Agent%20actions/%252Fapi%252Ffleet%252Fagents%252F%257BagentId%257D%252Factions%230
```
{
"item": {
"ack_data": "string",
"agents": [
"string"
],
"created_at": "string",
"data": "string",
"expiration": "string",
"id": "string",
"minimum_execution_duration": 0,
"namespaces": [
"string"
],
"rollout_duration_seconds": 0,
"sent_at": "string",
"source_uri": "string",
"start_time": "string",
"total": 0,
"type": "string"
}
}
```
The new spec should match the implementation accurately, and responses
are being verified when returned. Tests were added to make sure the
response schemas are correct.
If there are any bugs in the current schema, it will result in a HTTP
500 error with an error message on where the schema validation failed.
Example of an error where a field is missing:
```
{
"statusCode": 500,
"error": "Internal Server Error",
"message": "Failed output validation: [request body.items.0.name]: definition for this key is missing"
}
```
Example of an error where a field is mandatory in the schema, but not
provided in the response (missing `schema.maybe`)
```
{
"statusCode": 500,
"error": "Internal Server Error",
"message": "Failed output validation: [request body.items.0.internal]: expected value of type [boolean] but got [undefined]"
}
```
There are a few places where the validation allows unknown fields. Used
it where some fields were not included in TS types or fields are more
dynamic, e.g. fields coming from packages or elasticsearch settings.
https://github.com/search?q=repo%3Aelastic%2Fkibana+extendsDeep+path%3A%2F%5Ex-pack%5C%2Fplugins%5C%2Ffleet%5C%2Fserver%5C%2Ftypes%5C%2F%2F&type=code
```
.extendsDeep({
unknowns: 'allow',
})
```
Changes in this pr:
Remove using old `bundled.yaml` to generate oas, fixed tags.
Removed old openapi files, updated readme.
Here is the new bundle in Swagger UI:
[stateful](31f8cfd6ef/oas_docs/bundle.json)
[serverless](da72ee0093/oas_docs/bundle.serverless.json)
Updated serverless scripts too.
Updated Fleet readme:
da72ee0093/x-pack/plugins/fleet/common/openapi/README.md
Generated the new bundle by running this script locally:
```
node scripts/capture_oas_snapshot --include-path /api/fleet --update
```
---------
Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
*Epic:** https://github.com/elastic/security-team/issues/9401 (internal)
## Summary
This PR includes Security Solution OpenAPI domain bundles into the production OpenAPI Kibana bundle. The result Kibana bundler is expected to be published to Bump.sh manually by @lcawl.
**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.
