[Zod Helper][OAS Docs] Fix OAS docs generation for routes using buildRouteValidationWithZod#263354
Merged
[Zod Helper][OAS Docs] Fix OAS docs generation for routes using buildRouteValidationWithZod#263354
Conversation
Zod already treats all path params as required and this was breaking OAS docs generation.
kubasobon
added
release_note:skip
4 tasks
Member
Author
|
@elastic/kibana-core I'd appreciate a look here :) |
elastic-vault-github-plugin-prod
Bot
requested a review
from a team
as a code owner
Replace the parameter in Zod schemas because `.positive()` produces `exclusiveMinimum: 0` (OpenAPI 3.1 syntax) which is invalid in Kibana's OpenAPI 3.0 spec and increases the OAS validation error count, failing CI.
Contributor
💛 Build succeeded, but was flaky
Failed CI Steps
Test Failures
Metrics [docs]
History
cc @kubasobon |
romulets
reviewed
Apr 21, 2026
| maximum: 9007199254740991 | ||
| minimum: 1 | ||
| type: integer | ||
| fieldHistoryLength: |
Member
There was a problem hiding this comment.
@kubasobon maybe it's good that we add some very high max for docsLimit.
Also, there is no reason to keep fieldHistoryLength in the api. We are not using in the code right now.
If deleting fieldHistoryLength for now is too big, we can just make it positive or a max of 100 or smth
romulets
reviewed
Apr 21, 2026
| @@ -63959,7 +63995,93 @@ paths: | |||
|
|
|||
| List entity records from the Entity Store with paging, sorting, and filtering. Supports two modes: page-based pagination (page/per_page) and cursor-based pagination (searchAfter). The two modes cannot be combined.<br/><br/>[Required authorization] Route required privileges: securitySolution. | |||
| operationId: get-security-entity-store-entities | |||
| parameters: [] | |||
| parameters: | |||
| - description: A Kibana Query Language (KQL) filter for the search-after mode. | |||
Member
There was a problem hiding this comment.
I wonder if we need to publish the whole KQL api in our docs.....
romulets
reviewed
Apr 21, 2026
Comment on lines
+34
to
+35
| docsLimit: z.number().int().min(1).default(LOG_EXTRACTION_DOCS_LIMIT_DEFAULT), | ||
| maxLogsPerPage: z.number().int().min(1).default(LOG_EXTRACTION_MAX_LOGS_PER_PAGE_DEFAULT), |
Member
There was a problem hiding this comment.
relates to the max comment, just to avoid a max integer doc haha
Not sure if decreasing afterwards would lead to a considered breaking change? We can set to something that we know that it's a lot for our use case. Like docsLimit 1mil and maxLogsPerPage 10mil. Those max numbers are very very high
romulets
approved these changes
Apr 21, 2026
Member
Author
|
@romulets I appreciate the comments, we'll tackle those in V2 documentation. This PR is strictly towards fixing the generation code. Any changes to V2 docs made here are solely to avoid failures, not to make improvements. |
jesuswr
approved these changes
Apr 21, 2026
natasha-moore-elastic
approved these changes
Apr 21, 2026
Contributor
natasha-moore-elastic
left a comment
natasha-moore-elastic
left a comment
There was a problem hiding this comment.
Generated bump preview and verified that all query/path/body params are showing. Thanks for the fix!
alainnahalliday
approved these changes
Apr 21, 2026
kubasobon
added
backport:version
Contributor
|
Starting backport for target branches: 9.4 https://github.com/elastic/kibana/actions/runs/24720860299 |
Contributor
|
Starting backport for target branches: 9.4 https://github.com/elastic/kibana/actions/runs/24720860293 |
Contributor
💚 All backports created successfully
Note: Successful backport PRs will be merged automatically after passing CI. Questions ?Please refer to the Backport tool documentation |
kibanamachine
added a commit
to kibanamachine/kibana
that referenced
this pull request
Apr 21, 2026
…RouteValidationWithZod (elastic#263354) ## Summary When working on <elastic#262554> we have discovered both path and query parameters missing from generated OAS docs, despite being defined in the route itself. I have tracked the issue down to `buildRouteValidationWithZod` function obscuring the Zod schema. This PR aims to fix this issue by attaching the original, source schema to the output of `buildRouteValidationWithZod` and adding code to try and unwrap it in the `kbn-router-to-openapispec` code. This has no influence on existing code, other than correctly handling the routes with `buildRouteValidationWithZod`. ### Checklist Check the PR satisfies following conditions. Reviewers should verify this PR satisfies this list as well. - [x] [Unit or functional tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html) were updated or added to match the most common scenarios - [x] The PR description includes the appropriate Release Notes section, and the correct `release_note:*` label is applied per the [guidelines](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process) - [x] Review the [backport guidelines](https://docs.google.com/document/d/1VyN5k91e5OVumlc0Gb9RPa3h1ewuPE705nRtioPiTvY/edit?usp=sharing) and apply applicable `backport:*` labels. --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com> (cherry picked from commit f50036c)
Contributor
💚 All backports created successfully
Note: Successful backport PRs will be merged automatically after passing CI. Questions ?Please refer to the Backport tool documentation |
kibanamachine
added a commit
that referenced
this pull request
Apr 21, 2026
… buildRouteValidationWithZod (#263354) (#264675) # Backport This will backport the following commits from `main` to `9.4`: - [[Zod Helper][OAS Docs] Fix OAS docs generation for routes using buildRouteValidationWithZod (#263354)](#263354) <!--- Backport version: 9.6.6 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sorenlouv/backport) <!--BACKPORT [{"author":{"name":"Kuba Soboń","email":"wtty.fool@gmail.com"},"sourceCommit":{"committedDate":"2026-04-21T11:41:12Z","message":"[Zod Helper][OAS Docs] Fix OAS docs generation for routes using buildRouteValidationWithZod (#263354)\n\n## Summary\n\nWhen working on <#262554> we have\ndiscovered both path and query parameters missing from generated OAS\ndocs, despite being defined in the route itself. I have tracked the\nissue down to `buildRouteValidationWithZod` function obscuring the Zod\nschema.\n\nThis PR aims to fix this issue by attaching the original, source schema\nto the output of `buildRouteValidationWithZod` and adding code to try\nand unwrap it in the `kbn-router-to-openapispec` code. This has no\ninfluence on existing code, other than correctly handling the routes\nwith `buildRouteValidationWithZod`.\n\n\n### Checklist\n\nCheck the PR satisfies following conditions.\n\nReviewers should verify this PR satisfies this list as well.\n\n- [x] [Unit or functional\ntests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)\nwere updated or added to match the most common scenarios\n- [x] The PR description includes the appropriate Release Notes section,\nand the correct `release_note:*` label is applied per the\n[guidelines](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process)\n- [x] Review the [backport\nguidelines](https://docs.google.com/document/d/1VyN5k91e5OVumlc0Gb9RPa3h1ewuPE705nRtioPiTvY/edit?usp=sharing)\nand apply applicable `backport:*` labels.\n\n---------\n\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"f50036c6f1821d5dcf42158e30b3ec611ce94135","branchLabelMapping":{"^v9.5.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["technical debt","release_note:skip","backport:version","v9.4.0","v9.5.0"],"title":"[Zod Helper][OAS Docs] Fix OAS docs generation for routes using buildRouteValidationWithZod","number":263354,"url":"https://github.com/elastic/kibana/pull/263354","mergeCommit":{"message":"[Zod Helper][OAS Docs] Fix OAS docs generation for routes using buildRouteValidationWithZod (#263354)\n\n## Summary\n\nWhen working on <#262554> we have\ndiscovered both path and query parameters missing from generated OAS\ndocs, despite being defined in the route itself. I have tracked the\nissue down to `buildRouteValidationWithZod` function obscuring the Zod\nschema.\n\nThis PR aims to fix this issue by attaching the original, source schema\nto the output of `buildRouteValidationWithZod` and adding code to try\nand unwrap it in the `kbn-router-to-openapispec` code. This has no\ninfluence on existing code, other than correctly handling the routes\nwith `buildRouteValidationWithZod`.\n\n\n### Checklist\n\nCheck the PR satisfies following conditions.\n\nReviewers should verify this PR satisfies this list as well.\n\n- [x] [Unit or functional\ntests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)\nwere updated or added to match the most common scenarios\n- [x] The PR description includes the appropriate Release Notes section,\nand the correct `release_note:*` label is applied per the\n[guidelines](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process)\n- [x] Review the [backport\nguidelines](https://docs.google.com/document/d/1VyN5k91e5OVumlc0Gb9RPa3h1ewuPE705nRtioPiTvY/edit?usp=sharing)\nand apply applicable `backport:*` labels.\n\n---------\n\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"f50036c6f1821d5dcf42158e30b3ec611ce94135"}},"sourceBranch":"main","suggestedTargetBranches":["9.4"],"targetPullRequestStates":[{"branch":"9.4","label":"v9.4.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"main","label":"v9.5.0","branchLabelMappingKey":"^v9.5.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/263354","number":263354,"mergeCommit":{"message":"[Zod Helper][OAS Docs] Fix OAS docs generation for routes using buildRouteValidationWithZod (#263354)\n\n## Summary\n\nWhen working on <#262554> we have\ndiscovered both path and query parameters missing from generated OAS\ndocs, despite being defined in the route itself. I have tracked the\nissue down to `buildRouteValidationWithZod` function obscuring the Zod\nschema.\n\nThis PR aims to fix this issue by attaching the original, source schema\nto the output of `buildRouteValidationWithZod` and adding code to try\nand unwrap it in the `kbn-router-to-openapispec` code. This has no\ninfluence on existing code, other than correctly handling the routes\nwith `buildRouteValidationWithZod`.\n\n\n### Checklist\n\nCheck the PR satisfies following conditions.\n\nReviewers should verify this PR satisfies this list as well.\n\n- [x] [Unit or functional\ntests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)\nwere updated or added to match the most common scenarios\n- [x] The PR description includes the appropriate Release Notes section,\nand the correct `release_note:*` label is applied per the\n[guidelines](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process)\n- [x] Review the [backport\nguidelines](https://docs.google.com/document/d/1VyN5k91e5OVumlc0Gb9RPa3h1ewuPE705nRtioPiTvY/edit?usp=sharing)\nand apply applicable `backport:*` labels.\n\n---------\n\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"f50036c6f1821d5dcf42158e30b3ec611ce94135"}}]}] BACKPORT--> Co-authored-by: Kuba Soboń <wtty.fool@gmail.com>
spong
added a commit
that referenced
this pull request
May 1, 2026
…types (#267326) ### Summary Cleanup pass on `@kbn/evals-common` and the `evals` plugin, mirroring what was done for `@kbn/inbox-common` in #265634. No functional changes for end users, but the OAS docs generated from these routes are now correct, and the in-memory cost of the Zod schemas drops via the upstream lazy-bind optimization. ### Changes - **Switch to canonical `buildRouteValidationWithZod` from `@kbn/zod-helpers/v4`** - Deleted the local copy in `kbn-evals-common/impl/schemas/common.ts` and its re-export from `kbn-evals-common/index.ts`. - Updated all 18 evals route files to import the helper from `@kbn/zod-helpers/v4`. - Pruned `@kbn/zod-helpers` and `@kbn/core` from `kbn-evals-common`'s `moon.yml` / `tsconfig.json`; added `@kbn/zod-helpers` to the `evals` plugin's instead. - The canonical helper attaches `_sourceSchema` to the returned validator (added in #263354), which `kbn-router-to-openapispec` unwraps so route `params` / `query` / `body` actually appear in generated OAS docs. The local copy did not, so any OAS doc generation for these routes was silently dropping schema info. - **Regenerated OAS types** (`yarn openapi:generate` in `kbn-evals-common`) - Picks up the `lazySchema(() => …)` wrappers introduced by #264125 and tuned in #266343 (upstream `colinhacks/zod#5897` lazy-bind memory optimization). 19 `.gen.ts` files updated; pattern matches the prior inbox regen exactly. - **README cleanup** — pointed at the new helper location and dropped the obsolete "after regenerating, you may need to fix unused imports" workaround (no longer needed thanks to the OAS-generator `fix_eslint.ts` fix from #265634, which forces the non-editor branch when invoked from agent/IDE terminals). _PR developed with Cursor + Claude Opus 4.7 Super Duper xHigh Thinking++_
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
8 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.
Summary
When working on #262554 we have discovered both path and query parameters missing from generated OAS docs, despite being defined in the route itself. I have tracked the issue down to
buildRouteValidationWithZodfunction obscuring the Zod schema.This PR aims to fix this issue by attaching the original, source schema to the output of
buildRouteValidationWithZodand adding code to try and unwrap it in thekbn-router-to-openapispeccode. This has no influence on existing code, other than correctly handling the routes withbuildRouteValidationWithZod.Checklist
Check the PR satisfies following conditions.
Reviewers should verify this PR satisfies this list as well.
release_note:*label is applied per the guidelinesbackport:*labels.