[9.4] [Cases][Docs] - Add additional examples and cleanup to openApi (#263617)#265404
Merged
christineweng merged 4 commits intoelastic:9.4from Apr 24, 2026
Merged
Conversation
…ic#263617) ## Summary 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. ## The four kinds of fixes ### 1. Added missing "unauthorized" (401) examples 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. ### 2. Filled in missing code samples and request examples 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` ### 3. Schema inaccuracies — docs didn't match reality 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`. ### 4. Example payloads didn't match real API output 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`. ## Why the diff looks huge (+41,888 / −84,370) 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. ## Key files to actually review 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 ## Bottom line 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) # Conflicts: # src/platform/packages/private/kbn-validate-oas/src/oas_error_baseline.json # x-pack/platform/plugins/shared/cases/common/bundled-types.gen.ts
Contributor
💚 Build Succeeded
Metrics [docs]Async chunks
History
|
michaelolo24
approved these changes
Apr 24, 2026
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
4 participants
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