zod-openapi 4.2.3 → 5.0.0-beta.0

package/README.md

@@ -3,76 +3,52 @@
   <h1 align="center">zod-openapi</h1>
 </p>
 <p align="center">
-A Typescript library to use <a href="https://github.com/colinhacks/zod">Zod</a> Schemas to create OpenAPI v3.x documentation
+A TypeScript library which uses <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>
-<a href="https://www.npmjs.com/package/zod-openapi"><img src="https://img.shields.io/npm/dm/zod-openapi"/><a>
-<a href="https://nodejs.org/en/"><img src="https://img.shields.io/badge/node-%3E%3D%2018-brightgreen"/><a>
-<a href="https://github.com/samchungy/zod-openapi/actions/workflows/test.yml"><img src="https://github.com/samchungy/zod-openapi/actions/workflows/test.yml/badge.svg"/><a>
-<a href="https://github.com/samchungy/zod-openapi/actions/workflows/release.yml"><img src="https://github.com/samchungy/zod-openapi/actions/workflows/release.yml/badge.svg"/><a>
-<a href="https://github.com/seek-oss/skuba"><img src="https://img.shields.io/badge/🤿%20skuba-powered-009DC4"/><a>
+<a href="https://www.npmjs.com/package/zod-openapi"><img src="https://img.shields.io/npm/v/zod-openapi"/></a>
+<a href="https://www.npmjs.com/package/zod-openapi"><img src="https://img.shields.io/npm/dm/zod-openapi"/></a>
+<a href="https://nodejs.org/en/"><img src="https://img.shields.io/badge/node-%3E%3D%2018-brightgreen"/></a>
+<a href="https://github.com/samchungy/zod-openapi/actions/workflows/test.yml"><img src="https://github.com/samchungy/zod-openapi/actions/workflows/test.yml/badge.svg"/></a>
+<a href="https://github.com/samchungy/zod-openapi/actions/workflows/release.yml"><img src="https://github.com/samchungy/zod-openapi/actions/workflows/release.yml/badge.svg"/></a>
+<a href="https://github.com/seek-oss/skuba"><img src="https://img.shields.io/badge/🤿%20skuba-powered-009DC4"/></a>
 </div>
 <br>
 
-## Install
+## Installation
 
-Install via `npm`, `yarn` or `pnpm`:
+Install via `npm`, `yarn`, or `pnpm`:
 
 ```bash
 npm install zod zod-openapi
-## or
+# or
 yarn add zod zod-openapi
-## or
+# or
 pnpm install zod zod-openapi
 ```
 
 ## Usage
 
-### Extend Zod
+### `.meta()`
 
-This mutates Zod to add an extra `.openapi()` method. Call this at the top of your entry point(s). You can achieve this in two different ways, depending on your preference.
+Use the `.meta()` method to add metadata to a Zod schema. It accepts an object with the following options:
 
-#### Subpath Import
+| 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`            |
 
-```ts
-import 'zod-openapi/extend';
-import { z } from 'zod';
-
-z.string().openapi({ description: 'hello world!', example: 'hello world' });
-```
-
-#### Manual Extension
-
-This is useful if you have a specific instance of Zod or a Zod instance from another library that you would like to target.
-
-```typescript
-import { z } from 'zod';
-import { extendZodWithOpenApi } from 'zod-openapi';
-
-extendZodWithOpenApi(z);
-
-z.string().openapi({ description: 'hello world!', example: 'hello world' });
-```
-
-#### `.openapi()`
+`````typescript
 
-Use the `.openapi()` method to add metadata to a specific Zod type. The `.openapi()` method takes an object with the following options:
-
-|     Option      |                                                                      Description                                                                       |
-| :-------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------: |
-| OpenAPI Options |              This will take any option you would put on a [SchemaObject](https://swagger.io/docs/specification/data-models/data-types/).               |
-|  `effectType`   |                                           Use to override the creation type for a [Zod Effect](#zod-effects)                                           |
-|    `header`     |                                           Use to provide metadata for [response headers](#response-headers)                                            |
-|     `param`     |                                             Use to provide metadata for [request parameters](#parameters)                                              |
-|      `ref`      |                                  Use this to [auto register a schema as a re-usable component](#creating-components)                                   |
-|    `refType`    |                               Use this to set the creation type for a component which is not referenced in the document.                               |
-|     `type`      |                              Use this to override the generated type. If this is provided no metadata will be generated.                               |
-|  `unionOneOf`   | Set to `true` to force a single ZodUnion to output `oneOf` instead of `anyOf`. See [CreateDocumentOptions](#CreateDocumentOptions) for a global option |
+````typescript
 
 ### `createDocument`
 
-Creates an OpenAPI documentation object
+Generates an OpenAPI documentation object.
 
 ```typescript
 import 'zod-openapi/extend';
@@ -82,7 +58,7 @@ import { createDocument } from 'zod-openapi';
 const jobId = z.string().openapi({
   description: 'A unique identifier for a job',
   example: '12345',
-  ref: 'jobId',
+  id: 'jobId',
 });
 
 const title = z.string().openapi({
@@ -117,7 +93,7 @@ const document = createDocument({
     },
   },
 });
-```
+`````
 
 <details>
   <summary>Creates the following object:</summary>
@@ -204,9 +180,12 @@ const document = createDocument({
 
 ```typescript
 const document = createDocument(details, {
-  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.
+  override: ({ jsonSchema, zodSchema }) => {
+    if (jsonSchema.anyOf) {
+      ctx.jsonSchema.oneOf = ctx.jsonSchema.anyOf;
+      delete ctx.jsonSchema.anyOf;
+    }
+  },
 });
 ```
 
@@ -222,7 +201,7 @@ import { createSchema } from 'zod-openapi';
 const jobId = z.string().openapi({
   description: 'A unique identifier for a job',
   example: '12345',
-  ref: 'jobId',
+  id: 'jobId',
 });
 
 const title = z.string().openapi({
@@ -424,7 +403,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',
-  ref: 'jobTitle', // <- new field
+  id: 'jobTitle', // <- new field
 });
 ```
 
@@ -459,6 +438,10 @@ Another way to register schema instead of adding a `ref` is to add it to the com
 eg.
 
 ```typescript
+const title = z.string().openapi({
+  description: 'Job title',
+  example: 'My job',
+});
 createDocument({
   components: {
     schemas: {
@@ -468,8 +451,6 @@ createDocument({
 });
 ```
 
-Unfortunately, as a limitation of this library, you will need to 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. As a result, I recommend utilising the auto registering components over manual registration.
-
 #### Parameters
 
 Query, Path, Header & Cookie parameters can be similarly registered:
@@ -479,7 +460,7 @@ Query, Path, Header & Cookie parameters can be similarly registered:
 const jobId = z.string().openapi({
   description: 'Job ID',
   example: '1234',
-  param: { ref: 'jobRef' },
+  param: { id: 'jobRef' },
 });
 
 createDocument({
@@ -500,7 +481,7 @@ createDocument({
 const jobId = z.string().openapi({
   description: 'Job ID',
   example: '1234',
-  param: { in: 'header', name: 'jobId', ref: 'jobRef' },
+  param: { in: 'header', name: 'jobId', id: 'jobRef' },
 });
 
 createDocument({
@@ -537,7 +518,7 @@ Response headers can be similarly registered:
 const header = z.string().openapi({
   description: 'Job ID',
   example: '1234',
-  header: { ref: 'some-header' },
+  header: { id: 'some-header' },
 });
 
 // or
@@ -568,7 +549,7 @@ const response: ZodOpenApiResponseObject = {
       schema: z.object({ a: z.string() }),
     },
   },
-  ref: 'some-response',
+  id: 'some-response',
 };
 
 //or
@@ -597,7 +578,7 @@ Callbacks can also be registered
 
 ```typescript
 const callback: ZodOpenApiCallbackObject = {
-  ref: 'some-callback'
+  id: 'some-callback'
   post: {
     responses: {
       200: {
@@ -638,99 +619,77 @@ createDocument({
 });
 ```
 
-### Zod Effects
+### Zod Types
 
-`.transform()`, `.catch()`, `.default()` and `.pipe()` are complicated because they all comprise of two different types that we could generate (input & output).
+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.
 
-We attempt to determine what type of schema to create based on the following contexts:
+Input:
 
-_Input_: Request Bodies, Request Parameters, Headers
+- Request Parameters (query, path, header, cookie)
+- Request Body
 
-_Output_: Responses, Response Headers
+Output:
 
-As an example:
+- Response Body
+- 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()`.
 
 ```ts
-z.object({
-  a: z.string().default('a'),
+const schema = z.object({
+  name: z.string(),
 });
 ```
 
-In a request context, this would render the following OpenAPI schema:
-
-```yaml
-type: 'object'
-properties:
-  - a:
-    type: 'string'
-    default: 'a'
-```
-
-or the following for a response:
-
-```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.
+Input:
 
-#### EffectType
-
-```ts
-z.string().transform((str) => str.trim());
+```json
+{
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string"
+    }
+  },
+  "required": ["name"]
+}
 ```
 
-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`.
+Output:
 
-`same` - This informs Zod OpenAPI to pick either the input schema or output schema to generate with because they should be the same.
-
-```ts
-z.string()
-  .transform((str) => str.trim())
-  .openapi({ effectType: 'same' });
+```json
+{
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string"
+    }
+  },
+  "required": ["name"],
+  "additionalProperties": false
+}
 ```
 
-If the transform were to drift from this, you will receive a TypeScript error:
+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.
 
-```ts
-z.string()
-  .transform((str) => str.length)
-  .openapi({ effectType: 'same' });
-//           ~~~~~~~~~~
-//           Type 'same' is not assignable to type 'CreationType | undefined'.ts(2322)
-```
+If the schemas are not equal, it will automatically handle this by outputting the `output` schema with an `Output` suffix.
 
-`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.
+You can override this by setting the `outputId` field with the `.meta()` method.
 
 ```ts
-z.string()
-  .transform((str) => str.length)
-  .openapi({ effectType: 'input' });
+const schema = z
+  .object({
+    name: z.string(),
+  })
+  .meta({ id: 'MyObject', outputId: 'MyObjectResponse' });
 ```
 
-#### 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.
 
@@ -759,72 +718,6 @@ 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.createMediaTypeSchema = components.createMediaTypeSchema;
-exports.createParamOrRef = components.createParamOrRef;
-exports.getDefaultComponents = components.getDefaultComponents;
-exports.getZodObject = components.getZodObject;
+exports.createMediaTypeObject = components.createMediaTypeObject;
+exports.createParameter = components.createParameter;
+exports.createRegistry = components.createRegistry;
+exports.unwrapZodObject = components.unwrapZodObject;

package/dist/api.d.mts

@@ -1,3 +1,5 @@
-export { ComponentsObject, createComponents, getDefaultComponents } from './create/components.js';
-export { createMediaTypeSchema } from './create/content.js';
-export { createParamOrRef, getZodObject } from './create/parameters.js';
+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';

package/dist/api.d.ts

@@ -1,3 +1,5 @@
-export { ComponentsObject, createComponents, getDefaultComponents } from './create/components.js';
-export { createMediaTypeSchema } from './create/content.js';
-export { createParamOrRef, getZodObject } from './create/parameters.js';
+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';

package/dist/api.mjs

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