zod-openapi 3.0.1 → 3.1.1

package/README.md

@@ -8,7 +8,7 @@ A Typescript library to use <a href="https://github.com/colinhacks/zod">Zod</a>
 <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%2016.11-brightgreen"/><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>
@@ -59,16 +59,16 @@ z.string().openapi({ description: 'hello world!', example: 'hello world' });
 
 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 ZodUnion to output `oneOf` instead of `allOf`                            |
+|     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 `allOf`. See [CreateDocumentOptions](#CreateDocumentOptions) for a global option |
 
 ### `createDocument`
 
@@ -198,6 +198,87 @@ const document = createDocument({
   ```
 </details>
 
+#### CreateDocumentOptions
+
+`createDocument` takes an optional `CreateDocumentOptions` argument which can be used to modify how the document is created.
+
+```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 allOf. An `.openapi()` `unionOneOf` value takes precedence over this one.
+});
+```
+
+### `createSchema`
+
+Creates an OpenAPI Schema Object along with any registered components. OpenAPI 3.1.0 Schema Objects are fully compatible with JSON Schema.
+
+```typescript
+import 'zod-openapi/extend';
+import { z } from 'zod';
+import { createSchema } from 'zod-openapi';
+
+const jobId = z.string().openapi({
+  description: 'A unique identifier for a job',
+  example: '12345',
+  ref: 'jobId',
+});
+
+const title = z.string().openapi({
+  description: 'Job title',
+  example: 'My job',
+});
+
+const job = z.object({
+  jobId,
+  title,
+});
+
+const { schema, components } = createSchema(job);
+```
+
+<details>
+  <summary>Creates the following object:</summary>
+  
+  ```json
+  {
+    "schema": {
+      "type": "object",
+      "properties": {
+        "jobId": {
+          "$ref": "#/components/schemas/jobId"
+        },
+        "title": {
+          "type": "string",
+          "description": "Job title",
+          "example": "My job"
+        }
+      },
+      "required": ["jobId", "title"]
+    },
+    "components": {
+      "jobId": {
+        "type": "string",
+        "description": "A unique identifier for a job",
+        "example": "12345"
+      }
+    }
+  }
+  ```
+</details>
+
+#### CreateSchemaOptions
+
+`createSchema` takes an optional `CreateSchemaOptions` parameter which can also take the same options as [CreateDocumentOptions](#createdocumentoptions) along with the following options:
+
+```typescript
+const { schema, components } = createSchema(job, {
+  schemaType: 'input'; // This controls whether this should be rendered as a request (`input`) or response (`output`). Defaults to `output`
+  openapi: '3.0.0'; // OpenAPI version to use, defaults to `'3.1.0'`
+  components: { jobId: z.string() } // Additional components to use and create while rendering the schema
+})
+```
+
 ### Request Parameters
 
 Query, Path, Header & Cookie parameters can be created using the `requestParams` key under the `method` key as follows: