Named swagger schema about terminus HOT 4 OPEN

@andreafspeziale Sounds good to me! Would you like to create a PR? :)

from terminus.

@BrunnerLivio npm i/build is broken on my side using node v18.5.0.

No problems by using node v16.x.x. Wouldn't be useful to specify engines in the package.json?

I've also start testing what I was proposing above but unfortunately it is not 100% what I would like to achieve.

Adding title will add the name to the schema

but it will not possible to smoothly have it listed at the bottom

I'm not sure how to achieve it but my feeling is that the only way would be to have the schemas as classes and import them into the main.ts of the consumer application as extra schemas.

const swaggerDocument = SwaggerModule.createDocument(app, swaggerConfig, {
  extraModels: [Exception],
});

Any suggestion to this brainstorming?

from terminus.

@andreafspeziale

No problems by using node v16.x.x. Wouldn't be useful to specify engines in the package.json?

Yeah that'd be nice! Can you specify the version that is defined within the .nvmrc file?

I'm not sure how to achieve it but my feeling is that the only way would be to have the schemas as classes and import them into the main.ts of the consumer application as extra schemas.

I haven't looked too deeply into it, but it may be related to this issue.
Have you tried calling ApiExtraModels within health-check.decorator.ts (similar how ApiServiceUnavailableResponse is called)

from terminus.

@BrunnerLivio Oh! I didn't notice the nvm file. Using that was smooth, so far so good!

I checked the issue u linked above and following your suggestion I did some tests but unfortunately I never saw the schemas rendering at the bottom of the swagger page.

Maybe I'm just misunderstanding your suggestion.

Could you try to be more specific? I will be happy to try it out on my side!

By the way I developed a similar use-case, as you can see from the previous comment screenshot I've an Exception schema in the schema list at the bottom of the swagger page.

I achieved it by exporting a class and a decorator from one of my monorepo packages named common.

As mentioned the package exports the class and a decorator to be used in the controllers:

export class Exception extends HttpException {
  constructor(response: ExceptionResponse, status: number) {
    super(response, status);
  }

  @ApiProperty()
  code!: string;

  @ApiProperty()
  message!: string;

  @ApiPropertyOptional({
    oneOf: [
      {
        type: 'array',
        items: {
          type: 'string',
        },
      },
      {
        type: 'object',
        additionalProperties: { type: 'unknown' },
      },
    ],
  })
  details?: string[] | Record<string, unknown>;
}

export const ApiExceptionResponse = ({
  status,
  description,
  example,
  examples,
}: ApiExceptionResponseOptions) =>
  applyDecorators(
    ApiResponse({
      status,
      description,
      content: {
        'application/json': {
          schema: { $ref: getSchemaPath(Exception) },
          example,
          examples,
        },
      },
    }),
  );

export class CatsController {
  constructor(private readonly catsService: CatsService) {}

  @Get(':id')
  @ApiOperation({
    summary: 'Retrieves a cat by id',
    description: 'A Cat is a sample entity. If not found throws a NotFoundException.',
  })
  @ApiExceptionResponse({
    status: 400,
    example: httpExceptionExamples.ValidationException.value,
  })
  @ApiExceptionResponse({
    status: 404,
    example: httpExceptionExamples.NotFoundException.value,
  })
  async getConfiguration(@Param() { id }: CatParam): Promise<Cat> {
    const { id: _, ...res } = await this.catsService.getCat(id);
    return res;
  }
}

...
import { Exception } from 'common';
...
const swaggerConfig = new DocumentBuilder()
  .setTitle(name)
  .setDescription(`${name} RESTful API service.`)
  .setVersion(version)
  .build();

const swaggerDocument = SwaggerModule.createDocument(app, swaggerConfig, {
  extraModels: [Exception],
});

SwaggerModule.setup('swagger', app, swaggerDocument);

Let me know your thoughts!

P.s: I noticed that the package contains some files that I would not include

Do you want me to open an issue and update the [.npmignore](https://github.com/nestjs/terminus/blob/master/.npmignore) ignoring:

• .nvmrc
• .husky
• docker-compose.yml

Cheers and sorry for the late response I've been working on my first OS nestjs module!

from terminus.