*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.
**Relates to:** https://github.com/elastic/kibana/issues/184428
## Summary
This PR omit `Solution` from from tag names and titles in Security Solution's OpenAPI bundles based on Security Docs team recommendation.
## Summary
Creates CLI script tooling for building data, rules, exceptions, and
lists in any (local, cloud, serverless) environment for manual testing.
The initial commits here add generated clients for accessing security
solution, exceptions, and lists APIs and a placeholder script where
those clients are set up for use. See README for more details.
Much of the code in this PR is auto-generated clients. The hand written
code is intended to be primarily in `quickstart/modules/`, where we can
add wrapper code to simplify the process for common test environment
setup. For example, `createValueListException` takes an array of items
and some metadata and automatically creates a new value list and an
exception that references that value list. `/modules/data/` contains
functions to generate documents of arbitrary size, and we can add more
functions to create various other types of documents.
---------
Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
**Resolves:** https://github.com/elastic/kibana/issues/183375
## Summary
This PR implements functionality assigning a provided tag to OpenAPI `Operation object`s in the result bundle. Specified tag is also added as the only root level OpenAPI tag. This approach allows to produce domain bundles having a single tag assigned. At the next step domain bundles are merged together into single Kibana bundle where tags will allow to properly display grouping at Bump.sh (API reference documentation platform).
## Details
Bump.sh (our new API reference documentation platform) uses OpenAPI tags for grouping API endpoints. It supports only one tag per endpoint.
This PR facilitates preparation of Kibana OpenAPI bundle to be uploaded to Bump.sh by implementing functionality assigning a provided tag to OpenAPI `Operation object`s in the result domain bundles. It's implemented by providing an optional configuration option `assignTag` whose format is OpenAPI Tag Object. When `assignTag` isn't specified the bundler merges existing tags.
## Example
Consider the following bundling configuration
```js
const { bundle } = require('@kbn/openapi-bundler');
bundle({
// ...
options: {
assignTag: {
name: 'Some Domain API tag name',
description: 'Some Domain API description',
externalDocs: {
url: 'https://some-external-documentation-url',
description: 'External documentation description',
}
},
});
```
and source OpenAPI specs
**spec1.schema.yaml**
```yaml
openapi: 3.0.3
info:
title: Spec1
version: '2023-10-31'
paths:
/api/some_api:
get:
tags: ['Some local tag']
responses:
200:
content:
'application/json':
schema:
type: string
```
**spec2.schema.yaml**
```yaml
openapi: 3.0.3
info:
title: Spec2
version: '2023-10-31'
paths:
/api/some_api:
post:
tags: ['Some global tag']
responses:
200:
content:
'application/json':
schema:
type: string
tags:
- name: Some global tag
```
**spec2.schema.yaml**
```yaml
openapi: 3.0.3
info:
title: Spec3
version: '2023-10-31'
paths:
/api/another_api:
get:
responses:
200:
content:
'application/json':
schema:
type: string
```
After bundling above OpenAPI specs with the provided bundling script we'll get the following
**domain-bundle.schema.yaml**
```yaml
openapi: 3.0.3
info:
title: Bundled document
version: '2023-10-31'
paths:
/api/some_api:
get:
tags: ['Some Domain API tag name']
responses:
200:
content:
'application/json':
schema:
type: string
post:
tags: ['Some Domain API tag name']
responses:
200:
content:
'application/json':
schema:
type: string
/api/another_api:
get:
tags: ['Some Domain API tag name']
responses:
200:
content:
'application/json':
schema:
type: string
tags:
- name: Some Domain API tag name
description: Some Domain API description
externalDocs:
url: 'https://some-external-documentation-url'
description: External documentation description
```
**Resolves:** https://github.com/elastic/kibana/issues/189269
**Resolves:** https://github.com/elastic/kibana/issues/189270
## Summary
This PR adds an ability to specify OpenAPI `servers` and security requirements (`security`) to be used in the result bundle. `servers` and/or `security` in the source OpenAPI specs are be dropped when custom `servers` and/or `security` provided.
## Details
Kibana is usually deployed at a single access point and manages authentication in a central way. That way it's much more convenient to have control on what `servers` and `security` are present in the result bundles. It will help to avoid conflicts, duplicates and update them in centralized way.
This PR extends OpenAPI bundler configuration options with `prototypeDocument`. "Prototype" in the name means it's a prototype for the result. The bundler uses certain properties from that prototype OpenAPI document to add them to the result OpenAPI bundle. The following properties are used
- `info` representing OpenAPI Info object (former `options.specInfo`)
- `servers` OpenAPI Server Object Array
- `security` + `components.securitySchemes` OpenAPI Security Requirement Object Array + OpenAPI Security Schemes Object (validation checks that both fields are set otherwise an error is thrown)
For convenience `prototypeDocument` could be specified as a string path to a file containing prototype OpenAPI document.
## How to test?
`prototypeDocument` can be specified for `bundle` and `merge` utilities like the following
**bundle**
```js
const { bundle } = require('@kbn/openapi-bundler');
(async () => {
await bundle({
sourceGlob: 'source/glob/*.yaml',
outputFilePath: 'output/bundle.yaml,
options: {
prototypeDocument: {
info: {
title: 'Some title',
description: 'Some description',
},
servers: [{
url: 'https://{kibana_url}',
variables: {
kibana_url: {
default: 'localhost:5601',
}
}
}],
security: [{ ApiKeyAuth: [] }],
components: {
securitySchemes: {
ApiKeyAuth: {
type: 'apiKey',
in: 'header',
name: 'Authorization',
}
}
}
},
},
});
```
**bundle** with external prototype document
```js
const { bundle } = require('@kbn/openapi-bundler');
(async () => {
await bundle({
sourceGlob: 'source/glob/*.yaml',
outputFilePath: 'output/bundle.yaml,
options: {
prototypeDocument: 'path/to/prototype_document.yaml',,
},
});
```
**merge**
```js
const { merge } = require('@kbn/openapi-bundler');
(async () => {
await merge({
sourceGlobs: [
'absolute/path/to/file.yaml`,
'some/glob/*.schema.yaml',
],
outputFilePath: 'output/file/path/bundle.yaml',
options: {
prototypeDocument: {
info: {
title: 'Some title',
description: 'Some description',
},
servers: [{
url: 'https://{kibana_url}',
variables: {
kibana_url: {
default: 'localhost:5601',
}
}
}],
security: [{ ApiKeyAuth: [] }],
components: {
securitySchemes: {
ApiKeyAuth: {
type: 'apiKey',
in: 'header',
name: 'Authorization',
}
}
}
},
},
});
})();
```
**merge** with external prototype document
```js
const { merge } = require('@kbn/openapi-bundler');
(async () => {
await merge({
sourceGlobs: [
'absolute/path/to/file.yaml`,
'some/glob/*.schema.yaml',
],
outputFilePath: 'output/file/path/bundle.yaml',
options: {
prototypeDocument: 'path/to/prototype_document.yaml',
},
});
})();
```
The result bundles will contain specified `servers` and `security` while source `servers` and `security` will be dropped.
**Addresses**: https://github.com/elastic/kibana/issues/184428
## Summary
This PR adds scripts for automatic bundling of Lists API OpenAPI specs as a part of PR pipeline. Corresponding resulting bundles are automatically committed in the Lists common package `kbn-securitysolution-lists-common` in the `docs/openapi/ess/` and `docs/openapi/serverless` folders (similar to https://github.com/elastic/kibana/pull/186384).
