github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-19 23:39:42 -04:00
Code Issues Projects Releases Packages Wiki Activity
kibana/oas_docs
History
Exact
Jan Monschke da72ed698e
[8.16] [Threat Hunting Investigations] Improve API docs for notes/timeline (#213584) (#214533) 
# Backport

This will backport the following commits from `main` to `8.16`:
- [[Threat Hunting Investigations] Improve API docs for notes/timeline
(#213584)](https://github.com/elastic/kibana/pull/213584)

<!--- Backport version: 9.6.6 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sorenlouv/backport)

<!--BACKPORT [{"author":{"name":"Jan
Monschke","email":"jan.monschke@elastic.co"},"sourceCommit":{"committedDate":"2025-03-12T17:55:54Z","message":"[Threat
Hunting Investigations] Improve API docs for notes/timeline
(#213584)\n\n##
Summary\n\n[META\nissue](https://github.com/elastic/security-docs-internal/issues/57)\n\nThis
PR improves the API documentation for timeline/notes/pinned events\nas
per the definition in the meta issue.\n\n### Notes\n#### Timeline API\n-
`eventType`:\n\t- is always set to `all`\n\t- looks like it's been
superseded by dataView?\n\t- I marked it as `deperecated` \n-
`eventIdToNoteIds`:\n- there's a type mismatch between what the frontend
expects and what is\nreturned\n\t- also it does not seem to be used
anymore?\n\t- it needs to be investigated further\n#### Notes API\n-
`GlobalNote`:\n\t- looks like it's not used anymore\n\t- I removed it,
nothing broke\n- `eventIngested`, `eventTimestamp`, `eventDataView` and
`overrideOwner`\nare all not used on the patch note endpoint, I removed
them. The\n`event*` ones I have never seen before to be
honest.\n\n---------\n\nCo-authored-by: kibanamachine
<42973632+kibanamachine@users.noreply.github.com>\nCo-authored-by:
Elastic Machine
<elasticmachine@users.noreply.github.com>","sha":"e3311c516b45999e875b92ff14140a3197babfc6","branchLabelMapping":{"^v9.1.0$":"main","^v8.19.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","v9.0.0","Team:Threat
Hunting:Investigations","backport:all-open","v9.1.0"],"title":"[Threat
Hunting Investigations] Improve API docs for
notes/timeline","number":213584,"url":"https://github.com/elastic/kibana/pull/213584","mergeCommit":{"message":"[Threat
Hunting Investigations] Improve API docs for notes/timeline
(#213584)\n\n##
Summary\n\n[META\nissue](https://github.com/elastic/security-docs-internal/issues/57)\n\nThis
PR improves the API documentation for timeline/notes/pinned events\nas
per the definition in the meta issue.\n\n### Notes\n#### Timeline API\n-
`eventType`:\n\t- is always set to `all`\n\t- looks like it's been
superseded by dataView?\n\t- I marked it as `deperecated` \n-
`eventIdToNoteIds`:\n- there's a type mismatch between what the frontend
expects and what is\nreturned\n\t- also it does not seem to be used
anymore?\n\t- it needs to be investigated further\n#### Notes API\n-
`GlobalNote`:\n\t- looks like it's not used anymore\n\t- I removed it,
nothing broke\n- `eventIngested`, `eventTimestamp`, `eventDataView` and
`overrideOwner`\nare all not used on the patch note endpoint, I removed
them. The\n`event*` ones I have never seen before to be
honest.\n\n---------\n\nCo-authored-by: kibanamachine
<42973632+kibanamachine@users.noreply.github.com>\nCo-authored-by:
Elastic Machine
<elasticmachine@users.noreply.github.com>","sha":"e3311c516b45999e875b92ff14140a3197babfc6"}},"sourceBranch":"main","suggestedTargetBranches":[],"targetPullRequestStates":[{"branch":"9.0","label":"v9.0.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"url":"https://github.com/elastic/kibana/pull/214261","number":214261,"state":"MERGED","mergeCommit":{"sha":"77caf7c24a7424c52e5b37107768ce3d4ff15bfb","message":"[9.0]
[Threat Hunting Investigations] Improve API docs for notes/timeline
(#213584) (#214261)\n\n# Backport\n\nThis will backport the following
commits from `main` to `9.0`:\n- [[Threat Hunting Investigations]
Improve API docs for
notes/timeline\n(#213584)](https://github.com/elastic/kibana/pull/213584)\n\n\n\n###
Questions ?\nPlease refer to the [Backport
tool\ndocumentation](https://github.com/sorenlouv/backport)\n\n\n\nCo-authored-by:
Jan Monschke
<jan.monschke@elastic.co>"}},{"branch":"main","label":"v9.1.0","branchLabelMappingKey":"^v9.1.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/213584","number":213584,"mergeCommit":{"message":"[Threat
Hunting Investigations] Improve API docs for notes/timeline
(#213584)\n\n##
Summary\n\n[META\nissue](https://github.com/elastic/security-docs-internal/issues/57)\n\nThis
PR improves the API documentation for timeline/notes/pinned events\nas
per the definition in the meta issue.\n\n### Notes\n#### Timeline API\n-
`eventType`:\n\t- is always set to `all`\n\t- looks like it's been
superseded by dataView?\n\t- I marked it as `deperecated` \n-
`eventIdToNoteIds`:\n- there's a type mismatch between what the frontend
expects and what is\nreturned\n\t- also it does not seem to be used
anymore?\n\t- it needs to be investigated further\n#### Notes API\n-
`GlobalNote`:\n\t- looks like it's not used anymore\n\t- I removed it,
nothing broke\n- `eventIngested`, `eventTimestamp`, `eventDataView` and
`overrideOwner`\nare all not used on the patch note endpoint, I removed
them. The\n`event*` ones I have never seen before to be
honest.\n\n---------\n\nCo-authored-by: kibanamachine
<42973632+kibanamachine@users.noreply.github.com>\nCo-authored-by:
Elastic Machine
<elasticmachine@users.noreply.github.com>","sha":"e3311c516b45999e875b92ff14140a3197babfc6"}}]}]
BACKPORT-->
2025-03-14 10:39:54 -05:00
..
examples [8.16] [DOCS] Remove inference connector docs (#198633) (#199845) 2024-11-12 13:38:46 -06:00
linters [8.16] [OpenAPI] Add redocly lint configuration (#199360) (#199555) 2024-11-08 21:35:17 -06:00
output [8.16] [Threat Hunting Investigations] Improve API docs for notes/timeline (#213584) (#214533) 2025-03-14 10:39:54 -05:00
overlays [8.16] [OpenAPI] Fix Serverless API base URL (#202373) (#202585) 2024-12-03 10:51:27 -05:00
scripts [8.16][OpenAPI] Update branch detail in API introduction (#199883) 2024-11-12 17:44:41 -06:00
bundle.json [8.16] [OpenAPI][DOCS] Add descriptions for alerting rule flapping properties (#200112) (#200221) 2024-11-18 11:12:06 +01:00
kibana.info.yaml [8.16] [OpenAPI] Fix Serverless API base URL (#202373) (#202585) 2024-12-03 10:51:27 -05:00
makefile [8.16] [OAS] Publish OAS bundles to bump.sh (#197482) (#200136) 2024-11-27 15:58:38 +01:00
package-lock.json [8.16] [OAS] Publish OAS bundles to bump.sh (#197482) (#200136) 2024-11-27 15:58:38 +01:00
package.json [8.16] [OAS] Publish OAS bundles to bump.sh (#197482) (#200136) 2024-11-27 15:58:38 +01:00
README.md [8.16] [OAS] Publish OAS bundles to bump.sh (#197482) (#200136) 2024-11-27 15:58:38 +01:00

README.md

Kibana API reference documentation

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.