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 includeCreateProductDto
andUpdateProductDto
in Swagger documentation. ๐โจ - In
UpdateOrderRequestDto
, use@ApiProperty
to define an array with a choice betweenCreateProductDto
andUpdateProductDto
usingoneOf
. ๐๐งฉ - 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. ๐ ๏ธ๐จโ๐ป
Top comments (0)