[9.4] [Zod Helper][OAS Docs] Fix OAS docs generation for routes using buildRouteValidationWithZod (#263354)

src/platform/packages/shared/kbn-router-to-openapispec/src/oas_converter/index.test.ts

@@ -9,6 +9,8 @@
 
 import { OasConverter } from '.';
 import { schema } from '@kbn/config-schema';
+import { z } from '@kbn/zod/v4';
+import { buildRouteValidationWithZod } from '@kbn/zod-helpers/v4';
 
 describe('OasConverter', () => {
   it('converts schemas with refs', () => {
@@ -88,4 +90,63 @@ describe('OasConverter', () => {
       required: ['foo'],
     });
   });
+
+  describe('unwraps Zod schemas from buildRouteValidationWithZod', () => {
+    it('converts query parameters from a wrapped Zod schema', () => {
+      const converter = new OasConverter();
+      const querySchema = z.object({
+        include_components: z.boolean().optional().describe('Return component-level details'),
+        page: z.number().int().optional().describe('Page number'),
+      });
+      const wrapped = buildRouteValidationWithZod(querySchema);
+
+      const result = converter.convertQuery(wrapped);
+      expect(result.length).toBe(2);
+      expect(result.map((p) => p.name).sort()).toEqual(['include_components', 'page']);
+      expect(result.find((p) => p.name === 'include_components')).toMatchObject({
+        in: 'query',
+        required: false,
+        schema: { type: 'boolean' },
+        description: 'Return component-level details',
+      });
+    });
+
+    it('converts path parameters from a wrapped Zod schema', () => {
+      const converter = new OasConverter();
+      const paramsSchema = z.object({
+        entityType: z.enum(['user', 'host']).describe('The entity type'),
+      });
+      const wrapped = buildRouteValidationWithZod(paramsSchema);
+
+      const result = converter.convertPathParameters(wrapped, {
+        entityType: { optional: false },
+      });
+      expect(result.length).toBe(1);
+      expect(result[0]).toMatchObject({
+        name: 'entityType',
+        in: 'path',
+        required: true,
+        description: 'The entity type',
+      });
+    });
+
+    it('converts body schema from a wrapped Zod schema', () => {
+      const converter = new OasConverter();
+      const bodySchema = z.object({
+        name: z.string().describe('Entity name'),
+        tags: z.array(z.string()).optional().describe('Tags'),
+      });
+      const wrapped = buildRouteValidationWithZod(bodySchema);
+
+      const result = converter.convert(wrapped);
+      expect(result).toMatchObject({
+        type: 'object',
+        properties: {
+          name: { type: 'string', description: 'Entity name' },
+          tags: { type: 'array', items: { type: 'string' }, description: 'Tags' },
+        },
+        required: ['name'],
+      });
+    });
+  });
 });

src/platform/packages/shared/kbn-router-to-openapispec/src/oas_converter/index.ts

@@ -28,6 +28,17 @@ export class OasConverter {
     this.#env = env;
   }
 
+  /**
+   * Unwrap a RouteValidationFunction produced by buildRouteValidationWithZod
+   * so the original Zod schema is visible to the converter chain.
+   */
+  #unwrapSchema(schema: unknown): unknown {
+    if (typeof schema === 'function' && '_sourceSchema' in schema && schema._sourceSchema != null) {
+      return schema._sourceSchema;
+    }
+    return schema;
+  }
+
   #getConverter(schema: unknown) {
     return this.#converters.find((c) => c.is(schema))!;
   }
@@ -43,7 +54,8 @@ export class OasConverter {
   }
 
   public convert(schema: unknown) {
-    const { schema: oasSchema, shared } = this.#getConverter(schema)!.convert(schema, {
+    const unwrapped = this.#unwrapSchema(schema);
+    const { schema: oasSchema, shared } = this.#getConverter(unwrapped)!.convert(unwrapped, {
       env: this.#env,
       sharedSchemas: this.#sharedSchemas,
     });
@@ -52,16 +64,18 @@ export class OasConverter {
   }
 
   public convertPathParameters(schema: unknown, pathParameters: KnownParameters) {
-    const { params, shared } = this.#getConverter(schema).convertPathParameters(
-      schema,
+    const unwrapped = this.#unwrapSchema(schema);
+    const { params, shared } = this.#getConverter(unwrapped).convertPathParameters(
+      unwrapped,
       pathParameters
     );
     this.#addComponents(shared);
     return params;
   }
 
   public convertQuery(schema: unknown) {
-    const { query, shared } = this.#getConverter(schema).convertQuery(schema);
+    const unwrapped = this.#unwrapSchema(schema);
+    const { query, shared } = this.#getConverter(unwrapped).convertQuery(unwrapped);
     this.#addComponents(shared);
     return query;
   }

src/platform/packages/shared/kbn-zod-helpers/v4/build_route_validation_with_zod.ts

@@ -44,11 +44,14 @@ interface ZodSafeParseable<Output = any> {
 export function buildRouteValidationWithZod<Output>(
   schema: ZodSafeParseable<Output>
 ): RouteValidationFunction<Output> {
-  return (inputValue: unknown, validationResult: RouteValidationResultFactory) => {
+  const fn = (inputValue: unknown, validationResult: RouteValidationResultFactory) => {
     const decoded = schema.safeParse(inputValue);
 
     return decoded.success
       ? validationResult.ok(decoded.data)
       : validationResult.badRequest(stringifyZodError(decoded.error as any));
   };
+  // Expose the original Zod schema so the OAS generator can detect and convert it.
+  (fn as RouteValidationFunction<Output> & { _sourceSchema: unknown })._sourceSchema = schema;
+  return fn;
 }

x-pack/solutions/security/plugins/entity_store/server/domain/saved_objects/global_state/constants.ts

@@ -31,8 +31,8 @@ export const LogExtractionConfig = z.object({
     .string()
     .regex(/[smdh]$/)
     .default(LOG_EXTRACTION_DELAY_DEFAULT),
-  docsLimit: z.number().int().positive().default(LOG_EXTRACTION_DOCS_LIMIT_DEFAULT),
-  maxLogsPerPage: z.number().int().positive().default(LOG_EXTRACTION_MAX_LOGS_PER_PAGE_DEFAULT),
+  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),
   timeout: z
     .string()
     .regex(/[smdh]$/)

x-pack/solutions/security/plugins/entity_store/server/routes/apis/crud/create.ts

@@ -21,11 +21,9 @@ import {
 } from '../../../domain/errors';
 import { Entity } from '../../../../common/domain/definitions/entity.gen';
 
-const paramsSchema = z
-  .object({
-    entityType: z.enum(ALL_ENTITY_TYPES).describe('The entity type to create.'),
-  })
-  .required();
+const paramsSchema = z.object({
+  entityType: z.enum(ALL_ENTITY_TYPES).describe('The entity type to create.'),
+});
 
 export function registerCRUDCreate(router: EntityStorePluginRouter) {
   router.versioned

x-pack/solutions/security/plugins/entity_store/server/routes/apis/crud/get.ts

@@ -29,7 +29,7 @@ const querySchema = z
     size: z.coerce
       .number()
       .int()
-      .positive()
+      .min(1)
       .optional()
       .describe('Number of entities to return in search-after mode.'),
     searchAfter: z

x-pack/solutions/security/plugins/entity_store/server/routes/apis/crud/update.ts

@@ -21,11 +21,9 @@ import {
 } from '../../../domain/errors';
 import { Entity } from '../../../../common/domain/definitions/entity.gen';
 
-const paramsSchema = z
-  .object({
-    entityType: z.enum(ALL_ENTITY_TYPES).describe('The entity type to update.'),
-  })
-  .required();
+const paramsSchema = z.object({
+  entityType: z.enum(ALL_ENTITY_TYPES).describe('The entity type to update.'),
+});
 
 const querySchema = z.object({
   force: BooleanFromString.optional()

x-pack/solutions/security/plugins/entity_store/server/routes/apis/force_ccs_extract_to_updates.ts

@@ -25,7 +25,7 @@ const bodySchema = z.object({
   indexPatterns: z.array(z.string()).min(1),
   fromDateISO: z.string().datetime(),
   toDateISO: z.string().datetime(),
-  docsLimit: z.number().int().positive().optional(),
+  docsLimit: z.number().int().min(1).optional(),
 });
 
 export function registerForceCcsExtractToUpdates(router: EntityStorePluginRouter) {

x-pack/solutions/security/plugins/entity_store/server/routes/constants.ts

@@ -49,8 +49,8 @@ export const LogExtractionUpdateParams = z.object({
     .string()
     .regex(/[smdh]$/)
     .optional(),
-  docsLimit: z.number().int().positive().optional(),
-  maxLogsPerPage: z.number().int().positive().optional(),
+  docsLimit: z.number().int().min(1).optional(),
+  maxLogsPerPage: z.number().int().min(1).optional(),
 });
 
 export type LogExtractionBodyParams = LogExtractionInstallParams | LogExtractionUpdateParams;