feat(decorators): add style and explode options to @ApiProperty#3789
feat(decorators): add style and explode options to @ApiProperty#3789JadenKim-dev wants to merge 3 commits intonestjs:masterfrom
Conversation
Add `style` and `explode` properties to `ApiPropertyCommonOptions`, allowing nested object query parameters to be serialized using OpenAPI serialization styles such as `deepObject`.
There was a problem hiding this comment.
Pull request overview
This PR extends @ApiProperty options to support OpenAPI parameter serialization (style/explode), enabling nested query DTO properties to be emitted as a single ParameterObject (e.g. style: 'deepObject') rather than flattened query params.
Changes:
- Add
style?: ParameterStyleandexplode?: booleantoApiPropertyCommonOptions. - Add
SchemaObjectFactorytests assertingstyle/explodeare preserved on the generatedParameterObjectand that nested DTOs are not flattened. - Add
SwaggerExplorertests asserting nested query DTO properties emit a single query parameter withstyle=deepObject,explode=true, and a$refschema.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
lib/decorators/api-property.decorator.ts |
Extends @ApiProperty option typings to include parameter serialization fields (style, explode). |
test/services/schema-object-factory.spec.ts |
Adds coverage around createFromModel output for deepObject-style nested query params. |
test/explorer/swagger-explorer.spec.ts |
Verifies explorer output for nested query DTO parameters preserves style/explode and avoids flattening. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…t metadata style and explode are ParameterObject-only fields and should not leak into generated SchemaObjects. Omit them alongside link when reading API_MODEL_PROPERTIES metadata. Also remove unused QueryDto class from the schema-object-factory test.
…support-deepobject-style-in-api-property
|
@kamilmysliwiec One note: after merging the latest master, the build-and-test CI action is currently failing. This appears to be caused by an upstream issue introduced in #3802 (isConstEnumObject misidentifies regular TypeScript enums as const-enum objects), which is unrelated to the changes in this PR |
PR Checklist
Please check if your PR fulfills the following requirements:
PR Type
What kind of change does this PR introduce?
What is the current behavior?
@ApiPropertydoes not acceptstyleorexplodeoptions. When using a nested object as a query parameter (e.g.Geolocationinside aQueryDto), there is no way to specifystyle: 'deepObject'without a@ts-expect-errorworkaround.This causes Swagger UI to generate flat query strings like
?latitude=5&longitude=1instead of?geolocation[latitude]=5&geolocation[longitude]=1.Issue Number: #3495
What is the new behavior?
ApiPropertyCommonOptionsnow includes optionalstyle(typed asParameterStyle) andexplode(typed asboolean) properties. These values are passed through to the OpenAPIParameterObjectat the top level, enabling proper serialization of nested query parameters.Example usage:
Does this PR introduce a breaking change?
Other information