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