Handling Multiple Schemas in NestJS Swagger with @ApiProperty 🚀

Swagger simplifies API documentation, but handling multiple schemas can be challenging. In NestJS, you can use the @ApiProperty decorator to tackle this. Let's explore this in a scenario. 🧐

The Scenario 📜

Imagine building an e-commerce platform with NestJS. You have an endpoint to update orders, which can contain an array of products. These products can be newly created or updated, requiring two schemas. 🛒📦

Defining Product Schemas 📝

Start by defining product schemas. You have a Product class with id, name, and quantity. Create two DTOs: CreateProductDto and UpdateProductDto for product creation and updates. 📋🛍️

class Product {
  // Properties
}

class CreateProductDto extends OmitType(Product, ['id'] as const) {}
class UpdateProductDto extends Product {}

Handling Multiple Schemas 🤯

Now, let's handle multiple schemas within the UpdateOrderRequestDto, representing an order update request. This DTO includes an array of products, which can be of either CreateProductDto or UpdateProductDto. 🔄📑

@ApiExtraModels(CreateProductDto, UpdateProductDto)
class UpdateOrderRequestDto {
  // Properties

  @ApiProperty({
    type: 'array',
    oneOf: [
      { $ref: getSchemaPath(CreateProductDto) },
      { $ref: getSchemaPath(UpdateProductDto) },
    ],
  })
  @Transform(({ value }) => {
    // Transformation logic
  })
  products: (CreateProductDto | UpdateProductDto)[];
}

Here's the breakdown:

• Use @ApiExtraModels to include CreateProductDto and UpdateProductDto in Swagger documentation. 📚✨
• In UpdateOrderRequestDto, use @ApiProperty to define an array with a choice between CreateProductDtoand UpdateProductDto using oneOf. 📊🧩
• Utilize @Transform to conditionally transform data based on the id property for creation or update. 🔄🔀

Conclusion 🎉

Handling multiple schemas in NestJS Swagger enhances API documentation for complex data structures. By leveraging @ApiProperty, you can clearly define schemas, making your API documentation precise and comprehensible. 📖🚀

This approach simplifies API development with Swagger, resulting in well-documented and robust APIs. Mastering Swagger's features is key to creating efficient APIs that streamline your development workflow. 🛠️👨‍💻