Releases: asteasolutions/zod-to-openapi
v3.0.0
Summary
- Added support for Open API 3.1.0
- Add typing for
examplesanddefaultmetadata - Added discriminator key to
ZodDiscriminatedUnionschemas - Added support for
ZodDatetype - Added support for object inheritance when it's more than one level deep
- Added support for
default - Added support for
minLength/maxLengthonstringtype - Exposed a function
getOpenApiMetadatathat exposes all provided metada
Full Changelog: v2.3.0...v3.0.0
Migrating to v3.0.0
The v3.0.0 release comes out with support for OpenApi v3.1.0. This new version comes with some breaking changes around null values. Check the OpenApi changelog for more information.
How it affects @asteasolutions/zod-to-openapi
Schema generation
The generator constructor now takes 2 arguments - the second one being the version OpenApi target version. This version would be used when generating the schemas provided as the first argument.
So if you had something like this:
const generator = new OpenAPIGenerator(registry.definitions);it should become:
const generator = new OpenAPIGenerator(registry.definitions, '3.0.0'); // Where 3.0.0 can be replaced with your desired versionAdditionally the openapi version used to be passed in the config object of generateDocument. It should not be passed anymore since the version provided in the constructor is the one that would be used.
Types
We've updated our underlying library for OpenApi object types. As a result the .openapi method would not accept "random" keys that are not OpenApi specific. All additional keys must now follow the format x-{some-string}. This is expected since it better suites the OpenApi specification and if you used it with different keys it might have been incorrect to start with.
We've also separated the internal metadata provided to zod objects. That means that you cannot use .openapi to provide a refId or extendedFrom manually. That was never the intended behavior to start with. Those are meant for internal usage only and any changes to them might break the inner workings of the library.
Note: If for some reason you want to modify such properties manually, you can use the internal_openapi method added for every zod schema at your own risk.
v2.3.0
- Added support for numeric enums
- Added webhooks support (for OpenAPI 3.1)
Full Changelog: v2.2.0...v2.3.0
v2.2.0
- Support zod preprocessed schema
Full Changelog: v2.1.0...v2.2.0
v2.1.0
- Added support for integers
- Introduced string pattern and formats
- Allow for root level specification extensions
- Exported all OpenAPI types
- Treat omit/pick as new objects
Full Changelog: v2.0.0...v2.1.0
v2.0.0
Summary
- Multiple response bodies (#31) for different media types can now be used when specifying an endpoint.
- Multiple request bodies (#31) for different media types can now be used when specifying an endpoint.
- Request and response bodies can now be described using pure OpenAPI format and not only
zodschema.
Migrating to v2.0.0
Responses
The responses of an endpoint used to be described as a single object per status code. Inside this object a mediaType property was specified. The current structure allows for multiple mediaTypes to be passed by following the standard OpenAPI format. To do that a new content key was introduced explicitly for each status code and inside of it, any mediaType string can be used as a key. The value could either be a plain OpenAPI object definition or a zod schema.
Additionally since there can now be multiple response schemas per status code it did not make sense to keep the functionality where a description specified using the .openapi method was used. Instead the status code response description is moved to the top level following the OpenAPI specification.
So for example a path that looked like this:
registry.registerPath({
...
responses: {
200: {
mediaType: 'application/json',
schema: UserSchema.openapi({
description: 'Object with user data.',
}),
},
}
});should now be migrated to the following structure:
registry.registerPath({
...
responses: {
200: {
description: 'Object with user data.',
content: {
'application/json': {
schema: UserSchema,
},
},
},
},
});Request bodies
The mediaType of the requestBodyof an endpoint used to be hardcoded to application/json. The previous format used to be to provide a zod schema as the value for request.body. The current structure allows for multiple mediaTypes to be used by following the standard OpenAPI format. To do that a new content key was introduced and inside of it, any mediaType string can be used as a key. The value could either be a plain OpenAPI object definition or a zod schema.
So for example a path that looked like this:
registry.registerPath({
...
request: {
body: UserSchema,
},
responses: { ... }
});should now be migrated to the following structure:
registry.registerPath({
...
request: {
body: {
content: {
'application/json': {
schema: UserSchema,
},
},
},
},
responses: {...},
});