Wisemen One-Of Decorators

Features

✔ Document One of properties in OpenApi
✔ Scalable way to define polymorphic response without the need to change a shared file
✔ Easy type narrowing for consumers of OpenApi docs
✔ TypeScript Support – Fully typed for a smooth developer experience.

Philosophy

Some models have a common core but different variations based on a type discriminator. This package allows you to document these models in an OpenApi doc generated by Nestjs Swagger.

Example

@OneOfResponse(Notification) // -> register this class as the response for Notification
class NotificationResponse {
  @ApiProperty({type: 'string', format: 'uuid'})
  uuid: string

  @OneOfTypeApiProperty()   // -> defines the type descriminator
  type: NotificationType

  @OneOfMetaApiProperty()   // -> defines the meta property
  meta: unknown
}

@OneOfMeta(Notification, NotificationType.DRIVER_CREATED) // -> register this class as a meta object of notification
class DriverCreatedNotificaitonMeta {
  @ApiProperty({ type: String, format: 'uuid' })
  driverUuid: string

  @ApiProperty({ type: String })
  driverName: string
}


@OneOfApiExtraModels(Notification) // -> register one of models for notification
export class GetNotificationsResponse {
  @OneOfApiProperty(Notification, { isArray: true })  // -> register one of api property for response
  items: NotificationResponse[]
}

Deep Dive

Response

You need to define a OneOfResponse for a class. Which class is given to this decorator as an argument strictly speaking not important, but I consider it to be good practice to use the model for which this response is created.

The response should contain both a OneOfTypeApiProperty and a OneOfMetaApiProperty. OneOfTypeApiProperty is used to discriminate the type of the meta property. It's usually a type enum from the model for which you are creating a response. OneOfMetaApiProperty defines the key for which the meta docs will be generated.

@OneOfResponse(Notification) // -> register this class as the response for Notification
class NotificationResponse {
  @ApiProperty({type: 'string', format: 'uuid'})
  uuid: string

  @OneOfTypeApiProperty()   // -> defines the type descriminator
  type: NotificationType

  @OneOfMetaApiProperty()   // -> defines the meta property
  meta: unknown
}

Meta types

The meta type can be defined in a separate file. No changes need to be made to the other files where OneOf is used. OneOfMeta registers the object as one of the meta object which can exist in the model.

@OneOfMeta(
  Notification,                     // -> the model to which this meta object belongs
  NotificationType.DRIVER_CREATED   // -> the type associated with this meta object
)
class DriverCreatedNotificaitonMeta {
  @ApiProperty({ type: String, format: 'uuid' })
  driverUuid: string

  @ApiProperty({ type: String })
  driverName: string
}

Using the Generated Docs

As an API response

If you need to directly return a single response item in a controller, use the OneOfApiResponse. You do not need to define extra models.

@Controller('/notifications')
class NotificationController {
  @Get()
  @OneOfApiResponse(Notification, { /* other Api Response options */ })
  async getNotifications(): Promise<NotificationResponse> {
    // ...
  }
}

Nested in another response

If you need to include the response nested in another response, use the OneOfApiProperty. Here you must also define extra models.

@OneOfApiExtraModels(Notification) // -> register one of models for notification
export class GetNotificationsResponse {
  @OneOfApiProperty(Notification, { isArray: true })  // -> register one of api property for response
  items: NotificationResponse[]
}