zod-openapi - npm Package Compare versions

Comparing version 2.17.0 to 2.18.0-beta.0

lib-types/create/components.d.ts

 import type { ZodType } from 'zod';
 import type { oas30, oas31 } from '../openapi3-ts/dist';
-import type { ZodOpenApiComponentsObject, ZodOpenApiRequestBodyObject, ZodOpenApiResponseObject, ZodOpenApiVersion } from './document';
+import type { ZodOpenApiCallbackObject, ZodOpenApiComponentsObject, ZodOpenApiRequestBodyObject, ZodOpenApiResponseObject, ZodOpenApiVersion } from './document';
 export type CreationType = 'input' | 'output';
@@ -98,2 +98,14 @@ type BaseEffect = {
 export type RequestBodyComponentMap = Map<ZodOpenApiRequestBodyObject, RequestBodyComponent>;
+export interface BaseCallbackComponent {
+    ref: string;
+}
+export interface CompleteCallbackComponent extends BaseCallbackComponent {
+    type: 'complete';
+    callbackObject: ZodOpenApiCallbackObject | oas31.CallbackObject | oas30.CallbackObject;
+}
+export interface PartialCallbackComponent extends BaseCallbackComponent {
+    type: 'manual';
+}
+export type CallbackComponent = CompleteCallbackComponent | PartialCallbackComponent;
+export type CallbackComponentMap = Map<ZodOpenApiCallbackObject, CallbackComponent>;
 export interface ComponentsObject {
@@ -105,2 +117,3 @@ schemas: SchemaComponentMap;
     responses: ResponseComponentMap;
+    callbacks: CallbackComponentMap;
     openapi: ZodOpenApiVersion;
@@ -112,3 +125,4 @@ }
 export declare const createComponentRequestBodyRef: (requestBodyRef: string) => string;
+export declare const createComponentCallbackRef: (callbackRef: string) => string;
 export declare const createComponents: (componentsObject: ZodOpenApiComponentsObject, components: ComponentsObject) => oas31.ComponentsObject | undefined;
 export {};

lib-types/create/document.d.ts

@@ -29,3 +29,11 @@ import type { AnyZodObject, ZodType, ZodTypeDef } from 'zod';
 };
-export interface ZodOpenApiOperationObject extends Omit<oas31.OperationObject & oas30.OperationObject, 'requestBody' | 'responses' | 'parameters'> {
+export interface ZodOpenApiCallbacksObject extends oas31.ISpecificationExtension {
+    [name: string]: ZodOpenApiCallbackObject;
+}
+export interface ZodOpenApiCallbackObject extends oas31.ISpecificationExtension {
+    /** Use this field to auto register this callback object as a component */
+    ref?: string;
+    [name: string]: ZodOpenApiPathItemObject | string | undefined;
+}
+export interface ZodOpenApiOperationObject extends Omit<oas31.OperationObject & oas30.OperationObject, 'requestBody' | 'responses' | 'parameters' | 'callbacks'> {
     parameters?: Array<ZodType | oas31.ParameterObject | oas30.ParameterObject | oas31.ReferenceObject | oas30.ReferenceObject>;
@@ -35,2 +43,3 @@ requestBody?: ZodOpenApiRequestBodyObject;
     responses: ZodOpenApiResponsesObject;
+    callbacks?: ZodOpenApiCallbacksObject;
 }
@@ -56,2 +65,3 @@ export interface ZodOpenApiPathItemObject extends Omit<oas31.PathItemObject & oas30.PathItemObject, 'get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch' | 'trace'> {
     responses?: Record<string, ZodOpenApiResponseObject>;
+    callbacks?: Record<string, ZodOpenApiCallbackObject>;
 }
@@ -58,0 +68,0 @@ export type ZodOpenApiVersion = OpenApiVersion;

lib-types/create/paths.d.ts

 import type { oas31 } from '../openapi3-ts/dist';
 import { type ComponentsObject } from './components';
-import type { ZodOpenApiPathsObject, ZodOpenApiRequestBodyObject } from './document';
+import type { ZodOpenApiPathItemObject, ZodOpenApiPathsObject, ZodOpenApiRequestBodyObject } from './document';
 export declare const createRequestBody: (requestBodyObject: ZodOpenApiRequestBodyObject | undefined, components: ComponentsObject, subpath: string[]) => oas31.ReferenceObject | oas31.RequestBodyObject | undefined;
+export declare const createPathItem: (pathObject: ZodOpenApiPathItemObject, components: ComponentsObject, path: string[]) => oas31.PathItemObject;
 export declare const createPaths: (pathsObject: ZodOpenApiPathsObject | undefined, components: ComponentsObject) => oas31.PathsObject | undefined;

package.json

 {
   "name": "zod-openapi",
-  "version": "2.17.0",
+  "version": "2.18.0-beta.0",
   "description": "Convert Zod Schemas to OpenAPI v3.x documentation",
@@ -70,9 +70,9 @@ "keywords": [
   "devDependencies": {
-    "@redocly/cli": "1.11.0",
+    "@redocly/cli": "1.14.0",
     "@types/node": "^20.3.0",
     "eslint-plugin-zod-openapi": "^0.1.0",
-    "openapi3-ts": "4.3.1",
+    "openapi3-ts": "4.3.2",
     "skuba": "8.0.1",
-    "yaml": "2.4.1",
-    "zod": "3.23.3"
+    "yaml": "2.4.2",
+    "zod": "3.23.8"
   },
@@ -82,2 +82,3 @@ "peerDependencies": {
   },
+  "packageManager": "pnpm@9.0.5",
   "engines": {
@@ -84,0 +85,0 @@ "node": ">=16.11"

README.md

@@ -34,4 +34,6 @@ <p align="center">
 
-This mutates Zod to add an extra `.openapi()` method. Call this at the top of your entry point(s).
+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 differernt ways, depending on your preference.
 
+#### Subpath Import
+
 ```ts
@@ -44,8 +46,8 @@ import 'zod-openapi/extend';
 
-#### Manual
+#### Manual Extension
 
-This is useful if you have a different instance of Zod that you would like to extend.
+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 'another-lib';
+import { z } from 'zod';
 import { extendZodWithOpenApi } from 'zod-openapi';
@@ -68,3 +70,3 @@
 |     `param`     |                                Use to provide metadata for [request parameters](#parameters)                                |
-|      `ref`      |                                 Use this to [auto register a schema](#creating-components)                                  |
+|      `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.                  |
@@ -79,4 +81,5 @@ |     `type`      |                 Use this to override the generated type. If this is provided no metadata will be generated.                 |
 ```typescript
+import 'zod-openapi/extend';
 import { z } from 'zod';
-import { createDocument, extendZodWithOpenApi } from 'zod-openapi';
+import { createDocument } from 'zod-openapi';
 
@@ -123,44 +126,26 @@ const jobId = z.string().openapi({
 
-Generates the following object:
-
-```json
-{
-  "openapi": "3.1.0",
-  "info": {
-    "title": "My API",
-    "version": "1.0.0"
-  },
-  "paths": {
-    "/jobs/{jobId}": {
-      "put": {
-        "parameters": [
-          {
-            "in": "path",
-            "name": "jobId",
-            "description": "A unique identifier for a job",
-            "schema": {
-              "$ref": "#/components/schemas/jobId"
-            }
-          }
-        ],
-        "requestBody": {
-          "content": {
-            "application/json": {
+<details>
+  <summary>Creates the following object:</summary>
+  
+  ```json
+  {
+    "openapi": "3.1.0",
+    "info": {
+      "title": "My API",
+      "version": "1.0.0"
+    },
+    "paths": {
+      "/jobs/{jobId}": {
+        "put": {
+          "parameters": [
+            {
+              "in": "path",
+              "name": "jobId",
+              "description": "A unique identifier for a job",
               "schema": {
-                "type": "object",
-                "properties": {
-                  "title": {
-                    "type": "string",
-                    "description": "Job title",
-                    "example": "My job"
-                  }
-                },
-                "required": ["title"]
+                "$ref": "#/components/schemas/jobId"
               }
             }
-          }
-        },
-        "responses": {
-          "200": {
-            "description": "200 OK",
+          ],
+          "requestBody": {
             "content": {
@@ -171,5 +156,2 @@ "application/json": {
                   "properties": {
-                    "jobId": {
-                      "$ref": "#/components/schemas/jobId"
-                    },
                     "title": {
@@ -181,22 +163,45 @@ "type": "string",
                   },
-                  "required": ["jobId", "title"]
+                  "required": ["title"]
                 }
               }
             }
+          },
+          "responses": {
+            "200": {
+              "description": "200 OK",
+              "content": {
+                "application/json": {
+                  "schema": {
+                    "type": "object",
+                    "properties": {
+                      "jobId": {
+                        "$ref": "#/components/schemas/jobId"
+                      },
+                      "title": {
+                        "type": "string",
+                        "description": "Job title",
+                        "example": "My job"
+                      }
+                    },
+                    "required": ["jobId", "title"]
+                  }
+                }
+              }
+            }
           }
         }
       }
-    }
-  },
-  "components": {
-    "schemas": {
-      "jobId": {
-        "type": "string",
-        "description": "A unique identifier for a job",
-        "example": "12345"
+    },
+    "components": {
+      "schemas": {
+        "jobId": {
+          "type": "string",
+          "description": "A unique identifier for a job",
+          "example": "12345"
+        }
       }
     }
   }
-}
-```
+  ```
+</details>
 
@@ -293,2 +298,38 @@ ### Request Parameters
 
+### Callbacks
+
+```typescript
+createDocument({
+  paths: {
+    '/jobs': {
+      get: {
+        callbacks: {
+          onData: {
+            '{$request.query.callbackUrl}/data': {
+              post: {
+                requestBody: {
+                  content: {
+                    'application/json': { schema: z.object({ a: z.string() }) },
+                  },
+                },
+                responses: {
+                  200: {
+                    description: '200 OK',
+                    content: {
+                      'application/json': {
+                        schema: z.object({ a: z.string() }),
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+});
+```
+
 ### Creating Components
@@ -337,3 +378,3 @@
 
-This can be an extremely powerful way to generate better Open API documentation. There are some Open API features like [discriminator mapping](https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/) which require all schemas in the union to contain a ref.
+This can be an extremely powerful way to create less repetitive Open API documentation. There are some Open API features like [discriminator mapping](https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/) which require all schemas in the union to contain a ref.
 
@@ -491,2 +532,49 @@ ##### Manually Registering Schema
 
+#### Callbacks
+
+Callbacks can also be registered
+
+```typescript
+const callback: ZodOpenApiCallbackObject = {
+  ref: 'some-callback'
+  post: {
+    responses: {
+      200: {
+        description: '200 OK',
+        content: {
+          'application/json': {
+            schema: z.object({ a: z.string() }),
+          },
+        },
+      },
+    },
+  },
+};
+
+//or
+
+const callback: ZodOpenApiCallbackObject = {
+  post: {
+    responses: {
+      200: {
+        description: '200 OK',
+        content: {
+          'application/json': {
+            schema: z.object({ a: z.string() }),
+          },
+        },
+      },
+    },
+  },
+};
+
+createDocument({
+  components: {
+    callbacks: {
+      'some-callback': callback,
+    },
+  },
+});
+```
+
 ## Supported OpenAPI Versions
@@ -538,3 +626,3 @@
 - ZodDate
-  - `string` `type` mapping by default
+  - `type` is mapped as `string` by default
 - ZodDefault
@@ -569,3 +657,3 @@ - ZodDiscriminatedUnion
 - ZodSet
-  - Treated as an array with `uniqueItems` (you may need to add a pre-process)
+  - Treated as an array with `uniqueItems` (you may need to add a pre-process to convert it to a set)
 - ZodString
@@ -572,0 +660,0 @@ - `format` mapping for `.url()`, `.uuid()`, `.email()`, `.datetime()`, `.date()`, `.time()`, `.duration()`

New alerts

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

218308

increased by4.47%

Lines of code

5767

increased by3.82%

Number of lines in readme file

729

increased by13.73%

Worsened metrics

Number of package files

64

decreased by-1.54%

Number of low quality alerts

1

increased byInfinity%

No dependency changes