Use Zod Schemas to create OpenAPI v3.x documentation
MIT License
Full Changelog: https://github.com/samchungy/zod-openapi/compare/v2.18.0...v2.19.0-beta.1
Published by samchungy 4 months ago
Full Changelog: https://github.com/samchungy/zod-openapi/compare/v2.18.0...v2.19.0-beta.0
Published by samchungy 5 months ago
Full Changelog: https://github.com/samchungy/zod-openapi/compare/v2.17.0...v2.18.0
Published by samchungy 5 months ago
Full Changelog: https://github.com/samchungy/zod-openapi/compare/v2.17.0...v2.18.0-beta.0
Published by samchungy 6 months ago
Add Auto-Extend Zod Import by @samchungy in https://github.com/samchungy/zod-openapi/pull/261
Previously, you needed to extend Zod by importing a function and running it against Zod which is rather clunky:
import { z } from 'zod';
import { extendZodWithOpenApi } from 'zod-openapi';
extendZodWithOpenApi(z);
z.string().openapi({ description: 'hello world!', example: 'hello world' });
You can now replace it by importing the new subpath import:
import 'zod-openapi/extend';
import { z } from 'zod';
z.string().openapi({ description: 'hello world!', example: 'hello world' });
Full Changelog: https://github.com/samchungy/zod-openapi/compare/v2.16.0...v2.17.0
Published by samchungy 6 months ago
Full Changelog: https://github.com/samchungy/zod-openapi/compare/v2.16.0...v2.17.0-beta.3
Published by samchungy 6 months ago
Full Changelog: https://github.com/samchungy/zod-openapi/compare/v2.16.0...v2.17.0-beta.2
Published by samchungy 6 months ago
Full Changelog: https://github.com/samchungy/zod-openapi/compare/v2.16.0...v2.17.0-beta.1
Published by samchungy 6 months ago
.date()
, .time()
and .duration()
string formats by @samchungy in https://github.com/samchungy/zod-openapi/pull/252
.base64()
string contentEncoding
by @samchungy in https://github.com/samchungy/zod-openapi/pull/254
ZodBranded
, ZodCatch
and ZodReadonly
in discriminator keys by @samchungy in https://github.com/samchungy/zod-openapi/pull/255
ZodNativeEnum
in discriminated unions by @samchungy in https://github.com/samchungy/zod-openapi/pull/256
Full Changelog: https://github.com/samchungy/zod-openapi/compare/v2.15.2...v2.16.0
Published by samchungy 6 months ago
Simplify Types by @samchungy in https://github.com/samchungy/zod-openapi/pull/250
This reverts the peer dependency requirement for zod in v2.15.1 back to ^3.21.4 and simplifies the interfaces used in interface merging.
Full Changelog: https://github.com/samchungy/zod-openapi/compare/v2.15.1...v2.15.2
Published by samchungy 6 months ago
Restrict Peer Dep Version of Zod by @samchungy in https://github.com/samchungy/zod-openapi/pull/247
Due to breaking type changes upcoming in Zod 3.23.0, the versions of Zod are now restricted to ~3.21.4 || ~3.22.0
Full Changelog: https://github.com/samchungy/zod-openapi/compare/v2.15.0...v2.15.1
Published by samchungy 7 months ago
Support OpenAPI 3.1 const
value by @samchungy in https://github.com/samchungy/zod-openapi/pull/240
ZodLiteral values will now be represented using the const keyword instead of a single value enum array in OpenAPI 3.1.0.
The following object, this will be now rendered as such:
z.object({
foo: z.literal('foo')
});
foo:
type: 'string'
- enum:
- - 'foo'
+ const: 'foo'
z.literal(undefined)
is now treated the same way as z.undefined()
when used in objects.z.literal(null)
is now treated the same way as z.null()
.Full Changelog: https://github.com/samchungy/zod-openapi/compare/v2.14.0...v2.15.0
Published by samchungy 8 months ago
Full Changelog: https://github.com/samchungy/zod-openapi/compare/v2.13.0...v2.14.0
Published by samchungy 9 months ago
Introduce same
effectType by @samchungy in https://github.com/samchungy/zod-openapi/pull/217
This library now has a new effectType
when dealing with Zod Effects. In most scenarios, our users were using transform
to sanitise or transform while ensuring the type did not change, however, this library could not handle this.
The new same
option allows this library to pick the input Zod Type to produce a schema while ensuring that the input and output remain the same type.
For example: when creating a response (output) schema for the following type this library cannot hook into the TypeScript
compiler at runtime to understand that you wanted a string schema generated:
z.string().transform((string) => string.toUpperCase());
which meant that you had to declare the following in order to get it to work:
z.string().transform((string) => string.toUpperCase()).openapi({ effectType: 'input' });
// or
z.string().transform((string) => string.toUpperCase()).pipe(z.string());
However, in the first example this could be dangerous if a user was to change the transform to no longer be the same type:
z.string().transform((string) => string.length).openapi({ effectType: 'input' });
The new same
type allows us to avoid this mistake:
✅ z.string().transform((string) => string.toUpperCase()).openapi({ effectType: 'same' });
// Type '"same"' is not assignable to type 'CreationType | undefined'. ts(2322)
❌ z.string().transform((string) => string.length).openapi({ effectType: 'same' });
Refactor Effect Handling by @samchungy in https://github.com/samchungy/zod-openapi/pull/211, https://github.com/samchungy/zod-openapi/pull/214
This library now validates that effects used within registered Lazy schemas are not included in both input and output schemas. This could possibly be a breaking change if you were accidentally doing this.
This library should also provide clearer errors when using Zod Effects with registered components which should make it easier to deal with effects.
Before:
Error: {"_def":{"in":{"_def":{"checks":[],"typeName":"ZodString","coerce":false}},"out":{"_def":{"checks":[],"typeName":"ZodNumber","coerce":false}},"typeName":"ZodPipeline","openapi":{"description":"A name that describes the job","example":"Mid level developer"}}} at /job > post > request body > content > application/json > schema > property: title contains a transformation but is used in both an input and an output. This is likely a mistake. Set an `effectType`, wrap it in a ZodPipeline or assign it a manual type to resolve
After:
Error: The ZodPipeline at /job > post > request body > content > application/json > schema > property: title is used within a registered compoment schema (jobTitle) and contains an output transformation (ZodPipeline) defined at /job > get > responses > 200 > content > application/json > schema > property: title which is also used in an input schema.
This may cause the schema to render incorrectly and is most likely a mistake. You can resolve this by:
1. Setting an `effectType` on the transformation to `same` or `input` eg. `.openapi({type: 'same'})`
2. Wrapping the transformation in a ZodPipeline
3. Assigning a manual type to the transformation eg. `.openapi({type: 'string'})`
4. Removing the transformation
5. Deregistering the component containing the transformation
Add default as an effect by @samchungy in https://github.com/samchungy/zod-openapi/pull/215, https://github.com/samchungy/zod-openapi/pull/216
https://github.com/samchungy/zod-openapi/pull/175 added a change which would generate differences in the schema for input and outputs for a default schema. This may be a breaking change if you were using .default()
in a registered schema which is referenced in both a request and response schema. As such, effectType
can now also be used to change the rendered type.
Full Changelog: https://github.com/samchungy/zod-openapi/compare/v2.12.0...v2.13.0
Published by samchungy 10 months ago
effectType
error messages by @samchungy in https://github.com/samchungy/zod-openapi/pull/203
Full Changelog: https://github.com/samchungy/zod-openapi/compare/v2.11.0...v2.12.0
Published by samchungy 12 months ago
Fix Nullable Behaviour by @samchungy in https://github.com/samchungy/zod-openapi/pull/187
.nullable()
now renders differently for OpenAPI < 3.1.0
Previously a registered schema which was made nullable would render as:
{
oneOf: [
{ $ref: '#/components/schemas/a' },
{ nullable: true }
]
}
will now be rendered as:
{
allOf: [
{ $ref: '#/components/schemas/a' }
],
nullable: true
}
Similarly with nullable unions
{
anyOf: [
{ $ref: '#/components/schemas/a' },
{ $ref: '#/components/schemas/b' },
{ nullable: true }
]
}
Will now be rendered as:
{
anyOf: [
{ $ref: '#/components/schemas/a' },
{ $ref: '#/components/schemas/b' }
],
nullable: true
}
Full Changelog: https://github.com/samchungy/zod-openapi/compare/v2.10.0...v2.11.0
Published by samchungy 12 months ago
Add unionOneOf by @samchungy in https://github.com/samchungy/zod-openapi/pull/184
You can now use unionOneOf
to override the output of a ZodUnion to be a oneOf
schema instead of allOf
(default). Previously rendering an oneOf schema was only possible with a ZodDiscriminatedUnion.
Bundle Package with esbuild by @samchungy in https://github.com/samchungy/zod-openapi/pull/178
This should result in no changes to the public API, however, if you were previously reaching into the package paths internally you will now see an error.
Full Changelog: https://github.com/samchungy/zod-openapi/compare/v2.9.1...v2.10.0
Published by samchungy about 1 year ago
Bundle Package with esbuild by @samchungy in https://github.com/samchungy/zod-openapi/pull/178
This should result in no changes to the public API, however, if you were previously reaching into the internal files you will now see an error.
Full Changelog: https://github.com/samchungy/zod-openapi/compare/v2.9.1...v2.10.0-beta.1
Published by samchungy about 1 year ago
fix: default should be nonoptional in output state by @tomwwright in https://github.com/samchungy/zod-openapi/pull/175
When .default()
is used on a ZodObject property field in a response schema, it is now correctly reflected as a required field.
Full Changelog: https://github.com/samchungy/zod-openapi/compare/v2.9.0...v2.9.1
Published by samchungy about 1 year ago
.startsWith()
, .endsWith()
, .includes()
and multiple string patterns by @samchungy in https://github.com/samchungy/zod-openapi/pull/164
Full Changelog: https://github.com/samchungy/zod-openapi/compare/v2.8.0...v2.9.0