zod-openapi 5.0.0-beta.0 → 5.0.0-beta.1

package/README.md

@@ -3,7 +3,7 @@
   <h1 align="center">zod-openapi</h1>
 </p>
 <p align="center">
-A TypeScript library which uses <a href="https://github.com/colinhacks/zod">Zod</a> schemas to generate OpenAPI v3.x documentation.
+A TypeScript library for using <a href="https://github.com/colinhacks/zod">Zod</a> schemas to generate OpenAPI v3.x documentation.
 </p>
 <div align="center">
 <a href="https://www.npmjs.com/package/zod-openapi"><img src="https://img.shields.io/npm/v/zod-openapi"/></a>
@@ -29,22 +29,46 @@ pnpm install zod zod-openapi
 
 ## Usage
 
-### `.meta()`
+### Extending Zod
 
-Use the `.meta()` method to add metadata to a Zod schema. It accepts an object with the following options:
+This package extends Zod by adding an `.openapi()` method. Call this at the top of your entry point(s). You can apply this extension in two ways:
 
-| Option     | Description                                                                                                      |
-| ---------- | ---------------------------------------------------------------------------------------------------------------- |
-| `id`       | Registers a schema as a reusable OpenAPI component.                                                              |
-| `header`   | Adds metadata for [response headers](#response-headers).                                                         |
-| `param`    | Adds metadata for [request parameters](#parameters).                                                             |
-| `override` | Allows you to override the rendered OpenAPI schema. This takes either an object or a function                    |
-| `outputId` | Allows you to set a different ID for the output schema. This is useful when the input and output schemas differ. |
-| `unusedIO` | Allows you to set the `io` for an unused schema added to the components section. Defaults to `output`            |
+#### Subpath Import
 
-`````typescript
+```ts
+import 'zod-openapi/extend';
+import { z } from 'zod';
+
+z.string().openapi({ description: 'Hello world!', example: 'Hello world' });
+```
 
-````typescript
+#### Manual Extension
+
+This method is useful if you have a specific instance of Zod or a Zod instance from another library that you want to extend.
+
+```typescript
+import { z } from 'zod';
+import { extendZodWithOpenApi } from 'zod-openapi';
+
+extendZodWithOpenApi(z);
+
+z.string().openapi({ description: 'Hello world!', example: 'hello world' });
+```
+
+### `.openapi()`
+
+Use the `.openapi()` method to add metadata to a Zod schema. It accepts an object with the following options:
+
+| Option            | Description                                                                                                               |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `OpenAPI Options` | Accepts any option available for a [SchemaObject](https://swagger.io/docs/specification/data-models/data-types/).         |
+| `effectType`      | Overrides the creation type for a [Zod Effect](#zod-effects).                                                             |
+| `header`          | Adds metadata for [response headers](#response-headers).                                                                  |
+| `param`           | Adds metadata for [request parameters](#parameters).                                                                      |
+| `ref`             | Registers a schema as a reusable OpenAPI component.                                                                       |
+| `refType`         | Defines the creation type for a component not explicitly referenced in the document.                                      |
+| `type`            | Overrides the generated type. If provided, no metadata will be generated.                                                 |
+| `unionOneOf`      | Forces a `oneOf` instead of `anyOf` for unions. See [CreateDocumentOptions](#CreateDocumentOptions) for a global setting. |
 
 ### `createDocument`
 
@@ -58,7 +82,7 @@ import { createDocument } from 'zod-openapi';
 const jobId = z.string().openapi({
   description: 'A unique identifier for a job',
   example: '12345',
-  id: 'jobId',
+  ref: 'jobId',
 });
 
 const title = z.string().openapi({
@@ -93,7 +117,7 @@ const document = createDocument({
     },
   },
 });
-`````
+```
 
 <details>
   <summary>Creates the following object:</summary>
@@ -180,12 +204,9 @@ const document = createDocument({
 
 ```typescript
 const document = createDocument(details, {
-  override: ({ jsonSchema, zodSchema }) => {
-    if (jsonSchema.anyOf) {
-      ctx.jsonSchema.oneOf = ctx.jsonSchema.anyOf;
-      delete ctx.jsonSchema.anyOf;
-    }
-  },
+  defaultDateSchema: { type: 'string', format: 'date-time' }, // defaults to { type: 'string' }
+  unionOneOf: true, // defaults to false. Forces all ZodUnions to output oneOf instead of anyOf. An `.openapi()` `unionOneOf` value takes precedence over this one.
+  enforceDiscriminatedUnionComponents: true, // defaults to false. Throws an error if a Discriminated Union member is not registered as a component.
 });
 ```
 
@@ -201,7 +222,7 @@ import { createSchema } from 'zod-openapi';
 const jobId = z.string().openapi({
   description: 'A unique identifier for a job',
   example: '12345',
-  id: 'jobId',
+  ref: 'jobId',
 });
 
 const title = z.string().openapi({
@@ -403,7 +424,7 @@ If we take the example in `createDocument` and instead create `title` as follows
 const title = z.string().openapi({
   description: 'Job title',
   example: 'My job',
-  id: 'jobTitle', // <- new field
+  ref: 'jobTitle', // <- new field
 });
 ```
 
@@ -451,6 +472,30 @@ createDocument({
 });
 ```
 
+Unfortunately, as a limitation of this library, you should attach an `.openapi()` field or `.describe()` to the schema that you are passing into the components or you will not reap the full benefits of component generation.
+
+```ts
+// ❌ Avoid this
+const title = z.string();
+
+// ✅ Recommended ways
+const title = z.string().describe('Job title');
+const title = z.string().openapi({
+  description: 'Job title',
+  example: 'My job',
+});
+
+createDocument({
+  components: {
+    schemas: {
+      jobTitle: title,
+    },
+  },
+});
+```
+
+Overall, I recommend utilising the auto registering components over manual registration.
+
 #### Parameters
 
 Query, Path, Header & Cookie parameters can be similarly registered:
@@ -460,7 +505,7 @@ Query, Path, Header & Cookie parameters can be similarly registered:
 const jobId = z.string().openapi({
   description: 'Job ID',
   example: '1234',
-  param: { id: 'jobRef' },
+  param: { ref: 'jobRef' },
 });
 
 createDocument({
@@ -481,7 +526,7 @@ createDocument({
 const jobId = z.string().openapi({
   description: 'Job ID',
   example: '1234',
-  param: { in: 'header', name: 'jobId', id: 'jobRef' },
+  param: { in: 'header', name: 'jobId', ref: 'jobRef' },
 });
 
 createDocument({
@@ -518,7 +563,7 @@ Response headers can be similarly registered:
 const header = z.string().openapi({
   description: 'Job ID',
   example: '1234',
-  header: { id: 'some-header' },
+  header: { ref: 'some-header' },
 });
 
 // or
@@ -549,7 +594,7 @@ const response: ZodOpenApiResponseObject = {
       schema: z.object({ a: z.string() }),
     },
   },
-  id: 'some-response',
+  ref: 'some-response',
 };
 
 //or
@@ -578,7 +623,7 @@ Callbacks can also be registered
 
 ```typescript
 const callback: ZodOpenApiCallbackObject = {
-  id: 'some-callback'
+  ref: 'some-callback'
   post: {
     responses: {
       200: {
@@ -619,77 +664,99 @@ createDocument({
 });
 ```
 
-### Zod Types
-
-Zod types are composed of two different parts: the input and the output. This library decides which type to create based on if it is used in a request or response context.
+### Zod Effects
 
-Input:
+`.transform()`, `.catch()`, `.default()` and `.pipe()` are complicated because they all comprise of two different types that we could generate (input & output).
 
-- Request Parameters (query, path, header, cookie)
-- Request Body
+We attempt to determine what type of schema to create based on the following contexts:
 
-Output:
+_Input_: Request Bodies, Request Parameters, Headers
 
-- Response Body
-- Response Headers
+_Output_: Responses, Response Headers
 
-In general, you want to avoid using a registered input schema in an output context and vice versa. This is because the rendered input and output schemas of a simple Zod schema will differ, even with a simple Zod schema like `z.object()`.
+As an example:
 
 ```ts
-const schema = z.object({
-  name: z.string(),
+z.object({
+  a: z.string().default('a'),
 });
 ```
 
-Input:
+In a request context, this would render the following OpenAPI schema:
 
-```json
-{
-  "type": "object",
-  "properties": {
-    "name": {
-      "type": "string"
-    }
-  },
-  "required": ["name"]
-}
+```yaml
+type: 'object'
+properties:
+  - a:
+    type: 'string'
+    default: 'a'
 ```
 
-Output:
+or the following for a response:
 
-```json
-{
-  "type": "object",
-  "properties": {
-    "name": {
-      "type": "string"
-    }
-  },
-  "required": ["name"],
-  "additionalProperties": false
-}
+```yaml
+type: 'object'
+properties:
+  - a:
+    type: 'string'
+    default: 'a'
+required:
+  - a
+```
+
+Note how the response schema created an extra `required` field. This means, if you were to register a Zod schema with `.default()` as a component and use it in both a request or response, your schema would be invalid. Zod OpenAPI keeps track of this usage and will throw an error if this occurs.
+
+#### EffectType
+
+```ts
+z.string().transform((str) => str.trim());
 ```
 
-Unless you are strictly using `z.looseObject()`s or `z.strictObject()`s throughout your codebase you will likely run into issues where the input and output schemas differ. This library will do a best effort to check equality using a simple JSON.stringify() === JSON.stringify() check. If your registered schema contains dynamically created components, this will always fail.
+Whilst the TypeScript compiler can understand that the result is still a `string`, unfortunately we cannot introspect this as your transform function may be far more complicated than this example. To address this, you can set the `effectType` on the schema to `same`, `input` or `output`.
 
-If the schemas are not equal, it will automatically handle this by outputting the `output` schema with an `Output` suffix.
+`same` - This informs Zod OpenAPI to pick either the input schema or output schema to generate with because they should be the same.
 
-You can override this by setting the `outputId` field with the `.meta()` method.
+```ts
+z.string()
+  .transform((str) => str.trim())
+  .openapi({ effectType: 'same' });
+```
+
+If the transform were to drift from this, you will receive a TypeScript error:
 
 ```ts
-const schema = z
-  .object({
-    name: z.string(),
-  })
-  .meta({ id: 'MyObject', outputId: 'MyObjectResponse' });
+z.string()
+  .transform((str) => str.length)
+  .openapi({ effectType: 'same' });
+//           ~~~~~~~~~~
+//           Type 'same' is not assignable to type 'CreationType | undefined'.ts(2322)
 ```
 
+`input` or `output` - This tells Zod OpenAPI to pick a specific schema to create whenever we run into this schema, regardless of it is a request or response schema.
+
+```ts
+z.string()
+  .transform((str) => str.length)
+  .openapi({ effectType: 'input' });
+```
+
+#### Preprocess
+
+`.preprocess()` will always return the `output` type even if we are creating an input schema. If a different input type is required you can achieve this with a `.transform()` combined with a `.pipe()` or simply declare a manual `type` in `.openapi()`.
+
+#### Component Effects
+
+If you are adding a ZodSchema directly to the `components` section which is not referenced anywhere in the document, additional context may be required to create either an input or output schema. You can do this by setting the `refType` field to `input` or `output` in `.openapi()`. This defaults to `output` by default.
+
 ## Supported OpenAPI Versions
 
 Currently the following versions of OpenAPI are supported
 
+- `3.0.0`
+- `3.0.1`
+- `3.0.2`
+- `3.0.3`
 - `3.1.0`
-- `3.1.1`
 
 Setting the `openapi` field will change how the some of the components are rendered.
 
@@ -718,6 +785,72 @@ As an example `z.string().nullable()` will be rendered differently
 }
 ```
 
+## Supported Zod Schema
+
+- ZodAny
+- ZodArray
+  - `minItems`/`maxItems` mapping for `.length()`, `.min()`, `.max()`
+- ZodBigInt
+  - `integer` `type` and `int64` `format` mapping
+- ZodBoolean
+- ZodBranded
+- ZodCatch
+  - Treated as ZodDefault
+- ZodCustom
+- ZodDate
+  - `type` is mapped as `string` by default
+- ZodDefault
+- ZodDiscriminatedUnion
+  - `discriminator` mapping when all schemas in the union are [registered](#creating-components). The discriminator must be a `ZodLiteral`, `ZodEnum` or `ZodNativeEnum` with string values. Only values wrapped in `ZodBranded`, `ZodReadOnly` and `ZodCatch` are supported.
+- ZodEffects
+  - `transform` support for request schemas. See [Zod Effects](#zod-effects) for how to enable response schema support
+  - `pre-process` support. We assume that the input type is the same as the output type. Otherwise pipe and transform can be used instead.
+  - `refine` full support
+- ZodEnum
+- ZodIntersection
+- ZodLazy
+  - The recursive schema within the ZodLazy or the ZodLazy _**must**_ be registered as a component. See [Creating Components](#creating-components) for more information.
+- ZodLiteral
+- ZodNativeEnum
+  - supporting `string`, `number` and combined enums.
+- ZodNever
+- ZodNull
+- ZodNullable
+- ZodNumber
+  - `integer` `type` mapping for `.int()`
+  - `exclusiveMin`/`min`/`exclusiveMax`/`max` mapping for `.min()`, `.max()`, `lt()`, `gt()`, `.positive()`, `.negative()`, `.nonnegative()`, `.nonpositive()`.
+  - `multipleOf` mapping for `.multipleOf()`
+- ZodObject
+  - `additionalProperties` mapping for `.catchall()`, `.strict()`
+  - `allOf` mapping for `.extend()` when the base object is registered and does not have `catchall()`, `strict()` and extension does not override a field.
+- ZodOptional
+- ZodPipeline
+  - See [Zod Effects](#zod-effects) for more information.
+- ZodReadonly
+- ZodRecord
+- ZodSet
+  - Treated as an array with `uniqueItems` (you may need to add a pre-process to convert it to a set)
+- ZodString
+  - `format` mapping for `.url()`, `.uuid()`, `.email()`, `.datetime()`, `.date()`, `.time()`, `.duration()`, `.ip({ version: 'v4' })`, `.ip({ version: 'v6' })`, `.cidr({ version: 'v4' })`, `.cidr({ version: 'v6' })`
+  - `minLength`/`maxLength` mapping for `.length()`, `.min()`, `.max()`
+  - `pattern` mapping for `.regex()`, `.startsWith()`, `.endsWith()`, `.includes()`
+  - `contentEncoding` mapping for `.base64()` for OpenAPI 3.1.0+
+- ZodTuple
+  - `items` mapping for `.rest()`
+  - `prefixItems` mapping for OpenAPI 3.1.0+
+- ZodUndefined
+- ZodUnion
+  - By default it outputs an `anyOf` schema. Use `unionOneOf` to change this to output `oneOf` instead.
+- ZodUnknown
+
+If this library cannot determine a type for a Zod Schema, it will throw an error. To avoid this, declare a manual `type` in the `.openapi()` section of that schema.
+
+eg.
+
+```typescript
+z.custom().openapi({ type: 'string' });
+```
+
 ## Examples
 
 See the library in use in the [examples](./examples/) folder.

package/dist/api.cjs

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const components = require("./components.chunk.cjs");
 exports.createComponents = components.createComponents;
-exports.createMediaTypeObject = components.createMediaTypeObject;
-exports.createParameter = components.createParameter;
-exports.createRegistry = components.createRegistry;
-exports.unwrapZodObject = components.unwrapZodObject;
+exports.createMediaTypeSchema = components.createMediaTypeSchema;
+exports.createParamOrRef = components.createParamOrRef;
+exports.getDefaultComponents = components.getDefaultComponents;
+exports.getZodObject = components.getZodObject;

package/dist/api.d.mts

@@ -1,5 +1,3 @@
-export { createComponents, createRegistry } from './create/components.js';
-export { createMediaTypeObject } from './create/content.js';
-export { createParameter } from './create/parameters.js';
-export { unwrapZodObject } from './create/object.js';
-export { Override, isAnyZodType } from './zod.js';
+export { ComponentsObject, createComponents, getDefaultComponents } from './create/components.js';
+export { createMediaTypeSchema } from './create/content.js';
+export { createParamOrRef, getZodObject } from './create/parameters.js';

package/dist/api.d.ts

@@ -1,5 +1,3 @@
-export { createComponents, createRegistry } from './create/components.js';
-export { createMediaTypeObject } from './create/content.js';
-export { createParameter } from './create/parameters.js';
-export { unwrapZodObject } from './create/object.js';
-export { Override, isAnyZodType } from './zod.js';
+export { ComponentsObject, createComponents, getDefaultComponents } from './create/components.js';
+export { createMediaTypeSchema } from './create/content.js';
+export { createParamOrRef, getZodObject } from './create/parameters.js';

package/dist/api.mjs

@@ -1,8 +1,8 @@
-import { createComponents, createMediaTypeObject, createParameter, createRegistry, unwrapZodObject } from "./components.chunk.mjs";
+import { createComponents, createMediaTypeSchema, createParamOrRef, getDefaultComponents, getZodObject } from "./components.chunk.mjs";
 export {
   createComponents,
-  createMediaTypeObject,
-  createParameter,
-  createRegistry,
-  unwrapZodObject
+  createMediaTypeSchema,
+  createParamOrRef,
+  getDefaultComponents,
+  getZodObject
 };