v4.0.0

What's Changed

Breaking Changes 🛠

• .openapi() Breaking Change by @samchungy in #356

  .openapi() behaves a little differently now. It will now attempt to respect any previous openapi state and use it. This means that any metadata set on previous schema will now also be carried over to the next schema. Whilst I don't suspect this will impact too many users, it is still a breaking change.

      const FooSchema = z
        .string()
        .transform((str => str.trim())).openapi({ effectType: 'same', example: 'foo' });
      const BarSchema = FooSchema
        .openapi({ description: "bar" }); // in this version, this BarSchema now has `effectType: same` and `example: 'foo'` too

Why do we need this change?

1. Unintuitive Extension

   const FooSchema = z.string().openapi({ ref: 'string' });
   
   const BarSchema = z.object({
     a: FooSchema,
     b: FooSchema.openapi({ description: 'foo' }),
   });
   
   createSchema(BarSchema)

   This currently generates the following:

   {
     schema: {
       type: 'object',
       properties: {
         a: { '$ref': '#/components/schemas/string' },
         b: { type: 'string', description: 'foo' }
       },
       required: [ 'a', 'b' ]
     },
     components: { string: { type: 'string' } }
   }

   However, it's clear that the user simply wanted to reuse the FooSchema but describe it as something else later on.

   After:

   {
     schema: {
       type: 'object',
       properties: {
         a: { '$ref': '#/components/schemas/string' },
         b: { '$ref': '#/components/schemas/string', description: 'foo' }
       },
       required: [ 'a', 'b' ]
     },
     components: { string: { type: 'string' } }
   }

   This also fixes an issue with the following example where .describe() is used in place of description.

   	const FooSchema = z.string().openapi({ ref: 'string' });
   	
   	const BarSchema = z.object({
   	  a: FooSchema,
   	  b: FooSchema.describe('foo')
   	});
   	
   	createSchema(BarSchema)

   This scenario previously caused us to throw an error because it attempts to register the FooSchema twice with different objects.

2. Unregistered Base Schemas.

   Previously, if you were to use a schema like this, it would actually render an incorrect component. This change updates that behaviour to always generate the base schema as a component.

   Before:

   const FooSchema = z.string().uuid().openapi({ ref: 'id' });
   const BarSchema = FooSchema.describe('unique job id');
   createSchema(BarSchema)

   {
     schema: { '$ref': '#/components/schemas/id' },
     components: {
       id: { type: 'string', format: 'uuid', description: 'unique job id' }
     }
   }

   After:

   {
     schema: { '$ref': '#/components/schemas/id', description: 'unique job id' },
     components: { id: { type: 'string', format: 'uuid' } }
   }

   This change also updates some of the parsing logic for registered schemas with a description field.

   Before

    {
       'allOf': [
         '$ref': '#/components/schemas/foo',
         { "description": "bar"} ],
       ]
    }

   After in 3.1.0

   {
      '$ref': '#/components/schemas/foo',
      'description': 'bar',
   }

   After in 3.0.0

   {
      'allOf': [
        '$ref': '#/components/schemas/foo',
      ],
      'description': 'bar'
   }

   The nesting of additional fields alongside allOf has also been adjusted.

New Features 🎉

• Add multipleOf support by @samchungy in #358

  z.number().multipleOf(3);

  Should now generate the following:

  {
    type: 'number',
    multipleOf: 3,
  }

• Update Intersection Parser by @samchungy in #360

  This library will now attempt to flatten any intersection chains you may have which will reduce unnecessary nesting of allOf.

Full Changelog: v3.3.0...v4.0.0

v4.0.0-beta.0

Release v4.0.0-beta.0

v3.3.0

What's Changed

Minor Breaking Change

ZodCatch is now properly treated as a Zod Effect. This is because ZodCatch can take any invalid result, such as an undefined and transform it. As a result, we now treat it the same as a ZodDefault when it comes to schema generation.

Required Logic Changes

The way we determine if schemas are optional has been simplified and under the hood runs a .safeParse(undefined) with the schema we are checking. This removes the double traversal of the schema and has highlighted a couple errors in the schema generation.

ZodCustom should now be flagged properly as required when a validating function is passed to it. Thanks @pmsfc

ZodUnion can now accept z.undefined(), z.literal(undefined), z.never() values.

ZodObject can now accept z.literal(undefined) as a value.

New Contributors

• @pmsfc made their first contribution in #350

Full Changelog: v3.2.0...v3.3.0

v3.2.0

What's Changed

New Features 🎉

• Support changing the components reference path in createSchema by @samchungy in #348

Full Changelog: v3.1.1...v3.2.0

v3.1.1

What's Changed

Other Changes

• Fix createParamOrRef by @samchungy in #336

  This fixes a breaking change unintentionally introduced in the previous release.

Full Changelog: v3.1.0...v3.1.1

v3.1.0

What's Changed

New Features 🎉

• CreateDocumentOptions

  This adds a couple global options to allow you to change how your OpenAPI documentation is rendered. Previously you needed to apply these on a field level to every type. Check the README for more details.

  • Add default date schema option by @mdoi2 in #330
  • Add unionOneOf global override by @samchungy in #331

• Introduce createSchema by @samchungy in #325

  This enables users to be able to create individual schemas without needing to scaffold the whole createDocument function.

New Contributors

• @mdoi2 made their first contribution in #330

Full Changelog: v3.0.1...v3.1.0

v3.0.1

What's Changed

Breaking Changes 🛠

• Move api to zod-openapi/api by @samchungy in #316

  This moves some internal functions previously exported via the api namespace to a zod-openapi/api subpath import.

• Require Node 18 by @samchungy in #317

New Contributors

• @tmcw made their first contribution in #291

Full Changelog: v2.19.0...v3.0.1

v3.0.0-beta.0

What's Changed

Breaking Changes 🛠

• Move api import to subpath by @samchungy in #316
• Require Node 18 by @samchungy in #317

Other Changes

• Update README.md by @tmcw in #291

New Contributors

• @tmcw made their first contribution in #291

Full Changelog: v2.19.0...v3.0.0

v2.19.0

What's Changed

New Features 🎉

• This release addresses ESM/CJS and subpath type issues for this library but as a side-effect also contains some minor BREAKING CHANGES to the types. If you were previously importing types directly from a subpath, you will now need to import them directly from the lib. There should be effect on the runtime functionality of the library.

  - import { ServerObject } from 'zod-openapi/lib-types/openapi3-ts/dist/oas31';
  - declare const server: ServerObject;
  
  + import { oas31 } from 'zod-openapi 
  + declare const server: oas31.ServerObject;

  This change also omits some extraneous class and function types from the openapi3-ts types that this library re-exports.

Other Changes

• Publish with Crackle by @samchungy in #287
• Bump openapi3-ts from 4.3.2 to 4.3.3 by @dependabot in #284
• Optimise Types by @samchungy in #288

Full Changelog: v2.18.0...v2.19.0

v2.19.0-beta.1

What's Changed

Other Changes

• Adopt Crackle by @samchungy in #287
• Bump openapi3-ts from 4.3.2 to 4.3.3 by @dependabot in #284
• Optimise Types by @samchungy in #288

Full Changelog: v2.18.0...v2.19.0-beta.1