Question: How to document multiple responses?

[FranciscoKloganB]

Consider the code snippet below. How would this be implemented?

  @Post()
  @ZodResponse({
    status: HttpStatus.CREATED,
    type: CreateUserResponseBody,
  })
  @ZodResponse({
    status: HttpStatus.CONFLICT,
    type: ErrorResponseBody,
  })
  public async createUser(@Body() body: CreateUserRequestBody) {
    this.logger.debug('Processing a request to create a principal with type User');

    return await this.createUserPrincipalUseCase.execute({
      email: body.email,
      password: body.password,
    });
  }

[mathieuletyrant]

I have the same question, did you find a solution @FranciscoKloganB ?

[FranciscoKloganB]

Apologies for the delayed response @mathieuletyrant. I hadn't noticed you made this question. We did something to similar to what @benkroeger suggested with the following custom decorator.

import { applyDecorators } from "@nestjs/common";
import {
  ApiAcceptedResponse,
  ApiBadRequestResponse,
  ApiBody,
  ApiBodyOptions,
  ApiConflictResponse,
  ApiConsumes,
  ApiCreatedResponse,
  ApiForbiddenResponse,
  ApiNoContentResponse,
  ApiOkResponse,
  ApiOperation,
  ApiOperationOptions,
  ApiParam,
  ApiParamOptions,
  ApiPreconditionFailedResponse,
  ApiResponseOptions,
  ApiUnauthorizedResponse,
  ApiUnprocessableEntityResponse,
} from "@nestjs/swagger";

type MethodOptions = {
  apiBody?: ApiBodyOptions;
  apiConsumes?: string[];
  operations?: ApiOperationOptions;
  params?: ApiParamOptions[];
  acceptedResponse?: ApiResponseOptions;
  badRequestResponse?: ApiResponseOptions;
  conflictResponse?: ApiResponseOptions;
  createdResponse?: ApiResponseOptions;
  forbiddenResponse?: ApiResponseOptions;
  noContentResponse?: ApiResponseOptions;
  okResponse?: ApiResponseOptions;
  unauthorizedResponse?: ApiResponseOptions;
  unprocessableEntityResponse?: ApiResponseOptions;
  preconditionFailedResponse?: ApiResponseOptions;
};

export function OpenApiDocs(options?: MethodOptions) {
  const decorators: Array<MethodDecorator> = [];

  if (options?.apiBody) {
    decorators.push(ApiBody(options.apiBody));
  }

  if (options?.apiConsumes) {
    decorators.push(ApiConsumes(...options.apiConsumes));
  }

  if (options?.operations) {
    decorators.push(ApiOperation(options.operations));
  }

  if (options?.params && options.params.length > 0) {
    decorators.push(...options.params.map((paramOption) => ApiParam(paramOption)));
  }

  if (options?.acceptedResponse) {
    decorators.push(ApiAcceptedResponse(options.acceptedResponse));
  }

  if (options?.badRequestResponse) {
    decorators.push(ApiBadRequestResponse(options.badRequestResponse));
  }

  if (options?.conflictResponse) {
    decorators.push(ApiConflictResponse(options.conflictResponse));
  }

  if (options?.createdResponse) {
    decorators.push(ApiCreatedResponse(options.createdResponse));
  }

  if (options?.preconditionFailedResponse) {
    decorators.push(ApiPreconditionFailedResponse(options.preconditionFailedResponse));
  }

  if (options?.forbiddenResponse) {
    decorators.push(ApiForbiddenResponse(options.forbiddenResponse));
  }

  if (options?.noContentResponse) {
    decorators.push(ApiNoContentResponse(options.noContentResponse));
  }

  if (options?.okResponse) {
    decorators.push(ApiOkResponse(options.okResponse));
  }

  if (options?.unauthorizedResponse) {
    decorators.push(ApiUnauthorizedResponse(options.unauthorizedResponse));
  }

  if (options?.unprocessableEntityResponse) {
    decorators.push(ApiUnprocessableEntityResponse(options.unprocessableEntityResponse));
  }

  return applyDecorators(...decorators);
}

Usage

  @OpenApiDocs({
    badRequestResponse: {
      description: "The request is invalid",
      type: BadRequestErrorResponseBody.Output,
    },
    conflictResponse: {
      description: "The client already exists",
      type: ErrorResponseBody.Output,
    },
    createdResponse: {
      description: "The client was created successfully",
      type: CreateClientResponseBody.Output,
    },
  })
  @Post("authentication/clients")
  @ZodSerializerDto(CreateClientResponseBody)
  public async createClient() {
    return Promise.resolve({ id: 'foo' })
  }

[benkroeger]

this still only serializes one format though, right?

[FranciscoKloganB]

In case I understand your question correctly, yes: this is documentation only.

It does not magically apply ZodSerializerDto to all documented types.

[benkroeger]

for documentation purposes the best way is to use plain @ApiResponse decorators instead of @ZodResponse. Careful though - you'll then also have to manually apply the @ZodSerializerDto decorator if you want response serialization. I don't think the interceptor supports selecting between multiple schemas yet though