Real World Example

Companies that expose APIs to partners (Razorpay, Shiprocket, Delhivery) publish OpenAPI docs and SDKs generated from them. A paginated response wrapper is documented once with a generic helper:

src/common/swagger/api-paginated-response.decorator.ts

import { applyDecorators, Type } from '@nestjs/common';
import { ApiExtraModels, ApiOkResponse, getSchemaPath } from '@nestjs/swagger';
import { PageMetaDto } from '../dto/page-meta.dto';

export const ApiPaginatedResponse = <T extends Type<unknown>>(model: T) =>
  applyDecorators(
    ApiExtraModels(PageMetaDto, model),
    ApiOkResponse({
      schema: {
        properties: {
          data: { type: 'array', items: { $ref: getSchemaPath(model) } },
          meta: { $ref: getSchemaPath(PageMetaDto) },
        },
      },
    }),
  );

// @Get() @ApiPaginatedResponse(ProductDto) findAll(@Query() q: ProductQueryDto) {}

Example

Generate a TypeScript client for partners:

npx openapi-typescript http://localhost:3000/docs/json -o sdk/shopease.d.ts

Example output

✨ openapi-typescript 7.4.4
🚀 http://localhost:3000/docs/json → sdk/shopease.d.ts [48ms]

Partner API Docs

Example