[9.4] [Cases][Docs] - Add additional examples and cleanup to openApi (#263617)#265427
Open
michaelolo24 wants to merge 1 commit intoelastic:9.4from
Open
[9.4] [Cases][Docs] - Add additional examples and cleanup to openApi (#263617)#265427michaelolo24 wants to merge 1 commit intoelastic:9.4from
michaelolo24 wants to merge 1 commit intoelastic:9.4from
Conversation
…ic#263617) This PR is a housekeeping pass on the public API documentation for Kibana Cases. The docs had drifted from reality — some fields were missing, some examples were wrong, some endpoints had no code samples, and the docs validator was throwing 22 errors. This PR makes the docs match what the API actually returns, and gets the validator to pass cleanly. Nothing about the API itself changes. Only documentation and its generated bundles. Every Cases endpoint was missing an example for its 401 response, which tripped the validator. Rather than copy-pasting the same example 16 times, a shared `components/examples/response_401.yaml` was created and referenced everywhere. One endpoint (`paths/api@cases@alerts@{alertid}.yaml`) was also using a deprecated `example:` format and got converted to the modern `examples:` map. Four endpoints gained curl + Console code samples or request-body examples — most notably: - **File upload** (`paths/api@cases@{caseid}@files.yaml`) — now shows multipart form usage - **Push-to-connector** (`paths/api@cases@{caseid}@connector@{connectorid}@_push.yaml`) — clarified that no body is needed - **Delete comments** (both bulk and single) — added curl + Console samples Five query-parameter component files also got `example:` values so the rendered docs aren't blank: - `page_index.yaml` → `1` - `page_size.yaml` → `20` - `sort_order.yaml` → `desc` - `severity.yaml` → `low` - `search.yaml` → `Case title 1` Three notable gaps between docs and actual API responses: - **`incremental_id` on cases** — added to `case_response_properties.yaml` and `case_response_get_case.yaml`, with a note that it's populated asynchronously and won't appear in the immediate `POST` response. - **User-action `type` enum was stale** — had 11 values, should have had 16. Added `category`, `customFields`, `delete_case`, `extended_fields`, `observables` to `user_actions_find_response_properties.yaml`. - **`observableTypes` was completely missing** from the case-configuration response schema — added to `case_configure_response_properties.yaml`. Author tested example files against a live Kibana and patched discrepancies: - **`add_comment_response.yaml`** — was missing `pushed_at`, `pushed_by`, `updated_at`, `updated_by`, and `profile_uid` on `created_by`. - **`push_case_response.yaml`** — was missing `assignees`, `customFields`, `category`, and `profile_uid` on `created_by`/`updated_by`. Don't be alarmed by the size. The vast majority of the churn is in three regenerated files: - `oas_docs/output/kibana.yaml` (+40,991 / −84,137) - `x-pack/platform/plugins/shared/cases/docs/openapi/bundled-types.json` - `x-pack/platform/plugins/shared/cases/docs/openapi/bundled-types.schema.yaml` These are machine-generated bundles. A manual post-bundle fixup was applied to the schema YAML to convert Redocly's file-path discriminator mappings (`foo.yaml`) into the `#/components/schemas/foo` format that `kbn-openapi-bundler` requires, so that `make merge-api-docs-stateful` continues to work. The hand-written changes (everything non-generated) are concentrated in: - `components/examples/` — new shared 401 example + updated response examples - `components/parameters/` — added example values - `components/schemas/` — the three schema fixes - `paths/` — 16 path files got the 401 reference; a handful got new code samples Docs-only cleanup. No runtime behavior changes, no tests to run, just safer and more accurate public API documentation. Validator now passes with **0 errors**. - written with Claude --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com> (cherry picked from commit 61a520d)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Backport
This will backport the following commits from
mainto9.4:Questions ?
Please refer to the Backport tool documentation