# Backport
This will backport the following commits from `main` to `8.16`:
- [Added examples for necessary Entity Analytics OpenAPI docs
(#205439)](https://github.com/elastic/kibana/pull/205439)
<!--- Backport version: 9.6.4 -->
### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sorenlouv/backport)
<!--BACKPORT [{"author":{"name":"Jared
Burgett","email":"147995946+jaredburgettelastic@users.noreply.github.com"},"sourceCommit":{"committedDate":"2025-01-15T23:17:19Z","message":"Added
examples for necessary Entity Analytics OpenAPI docs (#205439)\n\n#
Summary\r\n\r\nAs part of the effort to add missing content for Security
APIs, this PR\r\nintroduces a few missing request, response, and
parameter examples for\r\nSecurity Entity Analytics APIs.\r\n\r\nAll of
the affected APIs are the Asset Criticality APIs.\r\n\r\n# How to
Test\r\n\r\nUntil the docs are deployed, this can be tested by
navigating to\r\nhttps://editor.swagger.io/ and pasting in the fully
bundled file, which\r\ncan be
found\r\n[here](f905638686/x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml)\r\nin
the PR\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine
<42973632+kibanamachine@users.noreply.github.com>\r\nCo-authored-by:
Elastic Machine
<elasticmachine@users.noreply.github.com>","sha":"f2c0ee8bd7a09a9b91465eba5d4567ca17e5fd27","branchLabelMapping":{"^v9.0.0$":"main","^v8.18.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","v9.0.0","v8.16.0","backport:version","v8.17.0","v8.18.0"],"title":"Added
examples for necessary Entity Analytics OpenAPI
docs","number":205439,"url":"https://github.com/elastic/kibana/pull/205439","mergeCommit":{"message":"Added
examples for necessary Entity Analytics OpenAPI docs (#205439)\n\n#
Summary\r\n\r\nAs part of the effort to add missing content for Security
APIs, this PR\r\nintroduces a few missing request, response, and
parameter examples for\r\nSecurity Entity Analytics APIs.\r\n\r\nAll of
the affected APIs are the Asset Criticality APIs.\r\n\r\n# How to
Test\r\n\r\nUntil the docs are deployed, this can be tested by
navigating to\r\nhttps://editor.swagger.io/ and pasting in the fully
bundled file, which\r\ncan be
found\r\n[here](f905638686/x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml)\r\nin
the PR\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine
<42973632+kibanamachine@users.noreply.github.com>\r\nCo-authored-by:
Elastic Machine
<elasticmachine@users.noreply.github.com>","sha":"f2c0ee8bd7a09a9b91465eba5d4567ca17e5fd27"}},"sourceBranch":"main","suggestedTargetBranches":["8.16","8.17"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","branchLabelMappingKey":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/205439","number":205439,"mergeCommit":{"message":"Added
examples for necessary Entity Analytics OpenAPI docs (#205439)\n\n#
Summary\r\n\r\nAs part of the effort to add missing content for Security
APIs, this PR\r\nintroduces a few missing request, response, and
parameter examples for\r\nSecurity Entity Analytics APIs.\r\n\r\nAll of
the affected APIs are the Asset Criticality APIs.\r\n\r\n# How to
Test\r\n\r\nUntil the docs are deployed, this can be tested by
navigating to\r\nhttps://editor.swagger.io/ and pasting in the fully
bundled file, which\r\ncan be
found\r\n[here](f905638686/x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml)\r\nin
the PR\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine
<42973632+kibanamachine@users.noreply.github.com>\r\nCo-authored-by:
Elastic Machine
<elasticmachine@users.noreply.github.com>","sha":"f2c0ee8bd7a09a9b91465eba5d4567ca17e5fd27"}},{"branch":"8.16","label":"v8.16.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.17","label":"v8.17.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.x","label":"v8.18.0","branchLabelMappingKey":"^v8.18.0$","isSourceBranch":false,"url":"https://github.com/elastic/kibana/pull/206877","number":206877,"state":"MERGED","mergeCommit":{"sha":"8b0c892c6ac1382b86fb4fe71dcede3097d91f62","message":"[8.x]
Added examples for necessary Entity Analytics OpenAPI docs (#205439)
(#206877)\n\n# Backport\n\nThis will backport the following commits from
`main` to `8.x`:\n- [Added examples for necessary Entity Analytics
OpenAPI
docs\n(#205439)](https://github.com/elastic/kibana/pull/205439)\n\n<!---
Backport version: 9.4.3 -->\n\n### Questions ?\nPlease refer to the
[Backport
tool\ndocumentation](https://github.com/sqren/backport)\n\n<!--BACKPORT
[{\"author\":{\"name\":\"Jared\nBurgett\",\"email\":\"147995946+jaredburgettelastic@users.noreply.github.com\"},\"sourceCommit\":{\"committedDate\":\"2025-01-15T23:17:19Z\",\"message\":\"Added\nexamples
for necessary Entity Analytics OpenAPI docs
(#205439)\\n\\n#\nSummary\\r\\n\\r\\nAs part of the effort to add
missing content for Security\nAPIs, this PR\\r\\nintroduces a few
missing request, response, and\nparameter examples for\\r\\nSecurity
Entity Analytics APIs.\\r\\n\\r\\nAll of\nthe affected APIs are the
Asset Criticality APIs.\\r\\n\\r\\n# How to\nTest\\r\\n\\r\\nUntil the
docs are deployed, this can be tested by\nnavigating
to\\r\\nhttps://editor.swagger.io/ and pasting in the fully\nbundled
file, which\\r\\ncan
be\nfound\\r\\n[here](f905638686/x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml)\\r\\nin\nthe
PR\\r\\n\\r\\n---------\\r\\n\\r\\nCo-authored-by:
kibanamachine\n<42973632+kibanamachine@users.noreply.github.com>\\r\\nCo-authored-by:\nElastic
Machine\n<elasticmachine@users.noreply.github.com>\",\"sha\":\"f2c0ee8bd7a09a9b91465eba5d4567ca17e5fd27\",\"branchLabelMapping\":{\"^v9.0.0$\":\"main\",\"^v8.18.0$\":\"8.x\",\"^v(\\\\d+).(\\\\d+).\\\\d+$\":\"$1.$2\"}},\"sourcePullRequest\":{\"labels\":[\"release_note:skip\",\"v9.0.0\",\"v8.16.0\",\"backport:version\",\"v8.17.0\",\"v8.18.0\"],\"title\":\"Added\nexamples
for necessary Entity Analytics
OpenAPI\ndocs\",\"number\":205439,\"url\":\"https://github.com/elastic/kibana/pull/205439\",\"mergeCommit\":{\"message\":\"Added\nexamples
for necessary Entity Analytics OpenAPI docs
(#205439)\\n\\n#\nSummary\\r\\n\\r\\nAs part of the effort to add
missing content for Security\nAPIs, this PR\\r\\nintroduces a few
missing request, response, and\nparameter examples for\\r\\nSecurity
Entity Analytics APIs.\\r\\n\\r\\nAll of\nthe affected APIs are the
Asset Criticality APIs.\\r\\n\\r\\n# How to\nTest\\r\\n\\r\\nUntil the
docs are deployed, this can be tested by\nnavigating
to\\r\\nhttps://editor.swagger.io/ and pasting in the fully\nbundled
file, which\\r\\ncan
be\nfound\\r\\n[here](f905638686/x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml)\\r\\nin\nthe
PR\\r\\n\\r\\n---------\\r\\n\\r\\nCo-authored-by:
kibanamachine\n<42973632+kibanamachine@users.noreply.github.com>\\r\\nCo-authored-by:\nElastic
Machine\n<elasticmachine@users.noreply.github.com>\",\"sha\":\"f2c0ee8bd7a09a9b91465eba5d4567ca17e5fd27\"}},\"sourceBranch\":\"main\",\"suggestedTargetBranches\":[\"8.16\",\"8.17\",\"8.x\"],\"targetPullRequestStates\":[{\"branch\":\"main\",\"label\":\"v9.0.0\",\"branchLabelMappingKey\":\"^v9.0.0$\",\"isSourceBranch\":true,\"state\":\"MERGED\",\"url\":\"https://github.com/elastic/kibana/pull/205439\",\"number\":205439,\"mergeCommit\":{\"message\":\"Added\nexamples
for necessary Entity Analytics OpenAPI docs
(#205439)\\n\\n#\nSummary\\r\\n\\r\\nAs part of the effort to add
missing content for Security\nAPIs, this PR\\r\\nintroduces a few
missing request, response, and\nparameter examples for\\r\\nSecurity
Entity Analytics APIs.\\r\\n\\r\\nAll of\nthe affected APIs are the
Asset Criticality APIs.\\r\\n\\r\\n# How to\nTest\\r\\n\\r\\nUntil the
docs are deployed, this can be tested by\nnavigating
to\\r\\nhttps://editor.swagger.io/ and pasting in the fully\nbundled
file, which\\r\\ncan
be\nfound\\r\\n[here](f905638686/x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml)\\r\\nin\nthe
PR\\r\\n\\r\\n---------\\r\\n\\r\\nCo-authored-by:
kibanamachine\n<42973632+kibanamachine@users.noreply.github.com>\\r\\nCo-authored-by:\nElastic
Machine\n<elasticmachine@users.noreply.github.com>\",\"sha\":\"f2c0ee8bd7a09a9b91465eba5d4567ca17e5fd27\"}},{\"branch\":\"8.16\",\"label\":\"v8.16.0\",\"branchLabelMappingKey\":\"^v(\\\\d+).(\\\\d+).\\\\d+$\",\"isSourceBranch\":false,\"state\":\"NOT_CREATED\"},{\"branch\":\"8.17\",\"label\":\"v8.17.0\",\"branchLabelMappingKey\":\"^v(\\\\d+).(\\\\d+).\\\\d+$\",\"isSourceBranch\":false,\"state\":\"NOT_CREATED\"},{\"branch\":\"8.x\",\"label\":\"v8.18.0\",\"branchLabelMappingKey\":\"^v8.18.0$\",\"isSourceBranch\":false,\"state\":\"NOT_CREATED\"}]}]\nBACKPORT-->\n\nCo-authored-by:
Jared Burgett
<147995946+jaredburgettelastic@users.noreply.github.com>"}}]}]
BACKPORT-->
Co-authored-by: Jared Burgett <147995946+jaredburgettelastic@users.noreply.github.com>
Documentation about our OpenAPI bundling workflow and configuration. See Kibana's hosted stateful and serverless docs.
Workflow
The final goal of this workflow is to produce an OpenAPI bundle containing all Kibana's public APIs.
Step 0
OAS from Kibana's APIs are continuously extracted and captured in bundle.json and bundle.serverless.json as fully formed OAS documentation. See node scripts/capture_oas_snapshot --help for more info.
These bundles form the basis of our OpenAPI bundles to which we append and layer extra information before publishing.
Step 1
Append pre-existing bundles not extracted from code using kbn-openapi-bundler to produce the final resulting bundles.
To add more files into the final bundle, edit the appropriate oas_docs/scripts/merge*.js files.
Step 2
Apply any final overalys to the document that might include examples or final tweaks (see the "Scripts" section for more details).
Scripts
The oas_docs/scripts folder contains scripts that point to the source domain-specific OpenAPI bundles and specify additional parameters for producing the final output bundle. Currently, there are the following scripts:
merge_ess_oas.js script produces production an output bundle for ESS
merge_serverless_oas.js script produces production an output bundle for Serverless
Output Kibana OpenAPI bundles
The oas_docs/output folder contains the final resulting Kibana OpenAPI bundles
kibana.yaml production ready ESS OpenAPI bundle
kibana.serverless.yaml production ready Serverless OpenAPI bundle
Bundling commands
Besides the scripts in the oas_docs/scripts folder, there is an oas_docs/makefile to simplify the workflow. Use make help to see available commands.
fae7f204bd