v2.0.0

Summary

1. Multiple response bodies (#31) for different media types can now be used when specifying an endpoint.
2. Multiple request bodies (#31) for different media types can now be used when specifying an endpoint.
3. Request and response bodies can now be described using pure OpenAPI format and not only zod schema.

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: {...},
});