Response format with pagination and Swagger

Hi everyone,

I’m recently run into the issue with Swagger response models and different response formats that @nestjsx/crud produces depending on the pagination options. By default, getManyBase returns data using this schema: Entity[], when offset and per_page are set: GetManyDefaultResponse<T>.

But for Swagger metadata only the 1st format is used. This might cause issues when API client is generated from metadata using tools like swagger-api/swagger-codegen.

As far as I know, it’s possible to set an alternative response model in OpenAPI 3 but this feature isn’t supported by @nestjs/swagger yet: https://github.com/nestjs/swagger/issues/43.

That would be nice to have all responses in the same format: GetManyDefaultResponse<T> or Entity[] (with meta in HTTP headers, for example X-Total-Count).

As a workaround, I’m overriding response metadata using ApiOkResponse decorator + an interceptor to transform responses.

[michaelyali]

Ok, guys. I think one response format would be the best way. Will add it to the next release.

[roland-chernov]

@DaVarga Another part of the workaround (in addition to the interceptor) is Swagger meta overriding (possible after #113).

1. Define generic class for the response model (similar to GetManyDefaultResponse interface but with optional props):

   class GetManyResponse<Entity> {
     @ApiModelProperty({ type: Object, isArray: true }) // will be overwritten
     public data: Entity[];
   
     @ApiModelPropertyOptional()
     public count?: number;
   // ...
   

2. Define a factory function:

   type Entity = Function;
   
   function getManyResponseFor(type: Entity): typeof GetManyResponse {
     class GetManyResponseForEntity<Entity> extends GetManyResponse<Entity> {
       @ApiModelProperty({ type, isArray: true })
       public data: Entity[];
     }
     Object.defineProperty(GetManyResponseForEntity, 'name', {
       value: `GetManyResponseFor${type.name}`,
     });
   
     return GetManyResponseForEntity;
   }
   

3. Add ApiOkResponse decorator to options:

   @Crud({
     model: {
       type: Company,
     },
     routes: {
       getManyBase: {
         interceptors: [GetManyResponseInterceptor],
         decorators: [
           ApiOkResponse({ type: getManyResponseFor(Company) }),
   // ...
   

Or as an alternative, simply pass total count as X-Total-Count header in an interceptor. Then no need to redefine Swagger meta.