[OAS][Detection Engine] Clean up remaining errors

[yctercero]

Summary

This PR updates OpenAPI (OAS) documentation for HTTP APIs (api/detection_engine, api/lists, api/exception_lists): clearer descriptions, summaries, examples (request/response/params), and deprecation notes where routes are legacy or migration-related.

Scope: spec / documentation only. It does not change request or response validation schemas, route handlers, or runtime behavior—only how those routes are described in the OAS layer.

Ran and found no more errors:

node scripts/validate_oas_docs.js \
  --path /api/detection_engine --path /api/detection_engine \
  --path /api/lists --path /api/lists \
  --path /api/exception_lists --path /api/exception_lists \
--path /api/exceptions --path /api/exceptions
 info About to validate spec at ./oas_docs/output/kibana.yaml
   │ warn ./oas_docs/output/kibana.yaml is NOT valid
   │ warn Found the following issues
   │
   │
   │
   │ warn Found 0 errors in ./oas_docs/output/kibana.yaml
 info About to validate spec at ./oas_docs/output/kibana.serverless.yaml
   │ warn ./oas_docs/output/kibana.serverless.yaml is NOT valid
   │ warn Found the following issues
   │
   │
   │
   │ warn Found 0 errors in ./oas_docs/output/kibana.serverless.yaml
 info Validation complete

[infra-vault-gh-plugin-prod]

Pinging @elastic/security-detection-engine (Team:Detection Engine)

[yctercero]

@PhilippeOberti the scripts keep adding this in. Could you confirm this is ok?

[PhilippeOberti]

I'm honestly not sure if it's ok, but looking at a neighbor's file, I see this for alert tags:

export const SetAlertTagsResponse = lazySchema(() => z.object({}).catchall(z.unknown()));

Introduced in this recent PR. So I'm guessing the answer is yes it's ok do to it?

[PhilippeOberti]

There is this same example for alert status:

export const SetAlertsStatusResponse = lazySchema(() => z.object({}).catchall(z.unknown()));

[maximpn]

FYI lazySchema() helper was introduced in @kbn/openapi-generator in #264125. This is an action item to mitigate significantly increased Kibana idle memory consumption.

Please let me know if some functionality doesn't work because of lazySchema() helper. The helper should be transparent for functionality. And our tests didn't reveal issues.

[yctercero]

@PhilippeOberti I'm waiting on green to merge after confirming with Maxim. Let me know if you feel any changes should be made and I'm happy to follow up.

[dhurley14]

DE changes lgtm but I have the same question for the SetAlertAssigneesResponse catchall. My initial feelings is it should be a little more specific perhaps? cc: @PhilippeOberti

[kibanamachine]

💛 Build succeeded, but was flaky

• Buildkite Build
• Commit: e91d650

Failed CI Steps

• x-pack/platform/test/serverless/functional/configs/observability/config.group1.ts
• FTR Configs #176
• FTR Configs #227

Test Failures

• [job] [logs] x-pack/platform/test/serverless/functional/configs/observability/config.group1.ts / Serverless Common UI - Home Page Sample data in serverless Sample data loads

Metrics [docs]

Async chunks

Total size of all lazy-loaded chunks that will be downloaded as the user navigates the app

id	before	after	diff
securitySolution	12.0MB	12.0MB	+63.0B

History

• 💚 Build #436421 succeeded f4bd657
• 💛 Build #435911 was flaky 6fca356
• 💛 Build #435805 was flaky 0c62a09
• 💛 Build #435668 was flaky 347b405
• 💚 Build #435285 succeeded de0dee4

cc @yctercero

[kibanamachine]

Starting backport for target branches: 9.4

https://github.com/elastic/kibana/actions/runs/25180470889

[kibanamachine]

💔 All backports failed

Status	Branch	Result
❌	9.4	Backport failed because of merge conflicts You might need to backport the following PRs to 9.4: - Fix OAS validation errors in entity analytics privilege monitoring APIs && Risk Score APIs (#265470) - [OAS] Improve spec descriptions, summaries, examples (#265153) - [Cases][Docs] - Add additional examples and cleanup to openApi (#263617) - [Entity Analytics] Add missing OpenAPI descriptions and examples to p… (#264778) - [Osquery] Enables OpenAPI documentation for 5 new Osquery 9.4 API endpoints (#262810)

Manual backport

To create the backport manually run:

node scripts/backport --pr 266228

Questions ?

Please refer to the Backport tool documentation