How to Define Multiple Named Examples for the Same Schema

[radulff]

Hello, I'm using the zod-to-openapi extension to generate OpenAPI documentation from my Zod schemas. I'm trying to create multiple named examples for a single request/response schema to illustrate different scenarios, such as success, failure, and processing states.

I want to define these examples within the schema itself using the .openapi() method, but I encountered two distinct issues.

Example Schema:

Here’s a simplified version of the schema I’m working with, using dummy data:

extendZodWithOpenApi(z);

const OrderStatus = z.enum(['Pending', 'Processing', 'Completed', 'Failed']) .describe('The current status of the order') .openapi({ example: 'Pending' });

const OrderData = z.object({ orderId: z.string().describe('Unique identifier for the order').openapi({ example: 'order-1234' }), status: OrderStatus, amount: z.number().describe('Total amount for the order').openapi({ example: 100 }), currency: z.string().describe('Currency for the order').openapi({ example: 'USD' }), createdAt: z.number().describe('Timestamp when the order was created').openapi({ example: 1627890246 }), updatedAt: z.number().describe('Timestamp when the order was last updated').optional().openapi({ example: 1627890280 }) }) .describe('Schema for order details') .openapi({ examples: [ { orderId: 'order-1234-success', status: 'Completed', amount: 100, currency: 'USD', createdAt: 1627890246, updatedAt: 1627890280 }, { orderId: 'order-5678-failed', status: 'Failed', amount: 100, currency: 'USD', createdAt: 1627890246, updatedAt: 1627890260 }, { orderId: 'order-9876-processing', status: 'Processing', amount: 100, currency: 'USD', createdAt: 1627890246 } ] });

Problem 1: TypeScript Types Not Recognizing Named Examples

When I attempt to use named examples within the .openapi() method (e.g., OrderSuccess, OrderFailed, OrderProcessing), TypeScript doesn’t recognize them correctly. This approach results in type errors, making it challenging to compile the project.

To overcome this, I switched to using unnamed examples (as shown in the code above), which resolves the type issues, but leads to the second problem.

Problem 2: OpenAPI Documentation Generation Crashes

Although using unnamed examples resolves the type issues, it causes the OpenAPI documentation generation to crash with the following error:

node_modules/@asteasolutions/zod-to-openapi/dist/index.cjs:84 : (_e = this._def.openapi) === null || _e === void 0 ? void 0 : _e._internal.extendedFrom, ^ TypeError: Cannot read properties of undefined (reading 'extendedFrom') at ZodObject.result.extend

It seems that the OpenAPI generator might not be handling the unnamed examples correctly, leading to this crash.

Questions:

For Problem 1: Am I structuring the examples field correctly within the .openapi() method? Is there a recommended way to define multiple named examples in a way that TypeScript can recognize them without causing type errors?

For Problem 2: Is there a known limitation or bug that causes the OpenAPI documentation generation to crash when using unnamed examples? If so, is there an alternative approach I should be using to avoid this issue?

Any guidance or examples of how to correctly structure these examples while maintaining TypeScript compatibility and ensuring the OpenAPI documentation generation works would be greatly appreciated!

Thank you in advance for your help!