Operatsiyalar

OpenAPI terminlariga ko'ra, yo'llar (/users yoki /reports/summary kabi) sizning API'ingiz taqdim etadigan endpointlar (resurslar) bo'lib, operatsiyalar esa bu yo'llarni boshqarish uchun ishlatiladigan HTTP metodlaridir (GET, POST yoki DELETE kabi).

Teglar

Controllerni ma'lum tegga biriktirish uchun @ApiTags(...tags) dekoratoridan foydalaning.

1@ApiTags('cats')
2@Controller('cats')
3export class CatsController {}

Headerlar

So'rovning bir qismi sifatida kutiladigan maxsus headerlarni belgilash uchun @ApiHeader() dan foydalaning.

1@ApiHeader({
2  name: 'X-MyHeader',
3  description: 'Custom header',
4})
5@Controller('cats')
6export class CatsController {}

Javoblar

Maxsus HTTP javobini belgilash uchun @ApiResponse() dekoratoridan foydalaning.

1@Post()
2@ApiResponse({ status: 201, description: 'The record has been successfully created.'})
3@ApiResponse({ status: 403, description: 'Forbidden.'})
4async create(@Body() createCatDto: CreateCatDto) {
5  this.catsService.create(createCatDto);
6}

Nest @ApiResponse dekoratoridan meros olgan qisqa API response dekoratorlari to'plamini taqdim etadi:

• @ApiOkResponse()
• @ApiCreatedResponse()
• @ApiAcceptedResponse()
• @ApiNoContentResponse()
• @ApiMovedPermanentlyResponse()
• @ApiFoundResponse()
• @ApiBadRequestResponse()
• @ApiUnauthorizedResponse()
• @ApiNotFoundResponse()
• @ApiForbiddenResponse()
• @ApiMethodNotAllowedResponse()
• @ApiNotAcceptableResponse()
• @ApiRequestTimeoutResponse()
• @ApiConflictResponse()
• @ApiPreconditionFailedResponse()
• @ApiTooManyRequestsResponse()
• @ApiGoneResponse()
• @ApiPayloadTooLargeResponse()
• @ApiUnsupportedMediaTypeResponse()
• @ApiUnprocessableEntityResponse()
• @ApiInternalServerErrorResponse()
• @ApiNotImplementedResponse()
• @ApiBadGatewayResponse()
• @ApiServiceUnavailableResponse()
• @ApiGatewayTimeoutResponse()
• @ApiDefaultResponse()

1@Post()
2@ApiCreatedResponse({ description: 'The record has been successfully created.'})
3@ApiForbiddenResponse({ description: 'Forbidden.'})
4async create(@Body() createCatDto: CreateCatDto) {
5  this.catsService.create(createCatDto);
6}

So'rov uchun qaytariladigan modelni ko'rsatish uchun klass yaratib, barcha xususiyatlarni @ApiProperty() dekoratori bilan belgilashimiz kerak.

1export class Cat {
2  @ApiProperty()
3  id: number;
4
5  @ApiProperty()
6  name: string;
7
8  @ApiProperty()
9  age: number;
10
11  @ApiProperty()
12  breed: string;
13}

Keyin Cat modeli javob dekoratorining type xususiyati bilan birgalikda ishlatilishi mumkin.

1@ApiTags('cats')
2@Controller('cats')
3export class CatsController {
4  @Post()
5  @ApiCreatedResponse({
6    description: 'The record has been successfully created.',
7    type: Cat,
8  })
9  async create(@Body() createCatDto: CreateCatDto): Promise<Cat> {
10    return this.catsService.create(createCatDto);
11  }
12}

Brauzerni ochib, generatsiya qilingan Cat modelini tekshirib ko'ramiz:

Har bir endpoint yoki controller uchun javoblarni alohida belgilash o'rniga, DocumentBuilder klassi yordamida barcha endpointlar uchun global javobni belgilashingiz mumkin. Bu yondashuv ilovangizdagi barcha endpointlar uchun global javob ko'rsatmoqchi bo'lsangiz foydali (masalan, 401 Unauthorized yoki 500 Internal Server Error kabi xatolar uchun).

1const config = new DocumentBuilder()
2  .addGlobalResponse({
3    status: 500,
4    description: 'Internal server error',
5  })
6  // other configurations
7  .build();

Fayl yuklash

Ma'lum metod uchun @ApiBody dekoratori va @ApiConsumes() yordamida fayl yuklashni yoqishingiz mumkin. Fayl yuklash texnikasidan foydalangan to'liq misol:

1@UseInterceptors(FileInterceptor('file'))
2@ApiConsumes('multipart/form-data')
3@ApiBody({
4  description: 'List of cats',
5  type: FileUploadDto,
6})
7uploadFile(@UploadedFile() file: Express.Multer.File) {}

Bu yerda FileUploadDto quyidagicha aniqlanadi:

1class FileUploadDto {
2  @ApiProperty({ type: 'string', format: 'binary' })
3  file: any;
4}

Bir nechta fayl yuklashni boshqarish uchun FilesUploadDto ni quyidagicha aniqlashingiz mumkin:

1class FilesUploadDto {
2  @ApiProperty({ type: 'array', items: { type: 'string', format: 'binary' } })
3  files: any[];
4}

Kengaytmalar

So'rovga Extension qo'shish uchun @ApiExtension() dekoratoridan foydalaning. Kengaytma nomi x- prefiksi bilan boshlanishi kerak.

1@ApiExtension('x-foo', { hello: 'world' })

Kengaytirilgan: Generic ApiResponse

Raw Definitions imkoniyati bilan Swagger UI uchun Generic sxema aniqlashimiz mumkin. Quyidagi DTO mavjud deb faraz qilamiz:

1export class PaginatedDto<TData> {
2  @ApiProperty()
3  total: number;
4
5  @ApiProperty()
6  limit: number;
7
8  @ApiProperty()
9  offset: number;
10
11  results: TData[];
12}

results ni bezatmaymiz, chunki keyinroq unga xom ta'rif beramiz. Endi boshqa DTO ni, masalan, CatDto ni quyidagicha aniqlaymiz:

1export class CatDto {
2  @ApiProperty()
3  name: string;
4
5  @ApiProperty()
6  age: number;
7
8  @ApiProperty()
9  breed: string;
10}

Endi PaginatedDto<CatDto> javobini quyidagicha belgilashimiz mumkin:

1@ApiOkResponse({
2  schema: {
3    allOf: [
4      { $ref: getSchemaPath(PaginatedDto) },
5      {
6        properties: {
7          results: {
8            type: 'array',
9            items: { $ref: getSchemaPath(CatDto) },
10          },
11        },
12      },
13    ],
14  },
15})
16async findAll(): Promise<PaginatedDto<CatDto>> {}

Bu misolda javobda PaginatedDto ning allOfi bo'lishi va results xususiyati Array<CatDto> turida bo'lishi ko'rsatilgan.

• getSchemaPath() funksiyasi berilgan model uchun OpenAPI Spec faylidan OpenAPI Schema yo'lini qaytaradi.
• allOf OAS 3 tomonidan turli meros bilan bog'liq use-case larni qamrab olish uchun taqdim etilgan tushuncha.

Oxir-oqibat, PaginatedDto hech bir controller tomonidan to'g'ridan-to'g'ri ishlatilmagani uchun SwaggerModule hali mos model ta'rifini generatsiya qila olmaydi. Bunday holatda uni Extra Model sifatida qo'shishimiz kerak. Masalan, controllerni quyidagicha @ApiExtraModels() dekoratori bilan belgilashimiz mumkin:

1@Controller('cats')
2@ApiExtraModels(PaginatedDto)
3export class CatsController {}

Endi Swaggerni ishga tushirsangiz, ushbu endpoint uchun generatsiya qilingan swagger.json dagi javob quyidagi ko'rinishda bo'ladi:

1"responses": {
2  "200": {
3    "description": "",
4    "content": {
5      "application/json": {
6        "schema": {
7          "allOf": [
8            {
9              "$ref": "#/components/schemas/PaginatedDto"
10            },
11            {
12              "properties": {
13                "results": {
14                  "$ref": "#/components/schemas/CatDto"
15                }
16              }
17            }
18          ]
19        }
20      }
21    }
22  }
23}

Uni qayta foydalanish mumkin bo'lishi uchun PaginatedDto uchun maxsus dekorator yaratishimiz mumkin, masalan:

1export const ApiPaginatedResponse = <TModel extends Type<any>>(
2  model: TModel,
3) => {
4  return applyDecorators(
5    ApiExtraModels(PaginatedDto, model),
6    ApiOkResponse({
7      schema: {
8        allOf: [
9          { $ref: getSchemaPath(PaginatedDto) },
10          {
11            properties: {
12              results: {
13                type: 'array',
14                items: { $ref: getSchemaPath(model) },
15              },
16            },
17          },
18        ],
19      },
20    }),
21  );
22};

SwaggerModule modelimiz uchun ta'rif generatsiya qilishi uchun uni kontrollerdagi PaginatedDto kabi qo'shimcha model sifatida kiritishimiz kerak.

Shu tariqa, endpointimizda maxsus @ApiPaginatedResponse() dekoratoridan foydalanishimiz mumkin:

1@ApiPaginatedResponse(CatDto)
2async findAll(): Promise<PaginatedDto<CatDto>> {}

Mijoz generatorlari uchun bu yondashuv PaginatedResponse<TModel> klient uchun qanday generatsiya qilinishida noaniqlik keltirib chiqarishi mumkin. Quyidagi parcha kod yuqoridagi GET / endpointi uchun mijoz generatori natijasiga misol:

1// Angular
2findAll(): Observable<{ total: number, limit: number, offset: number, results: CatDto[] }>

Ko'rib turganingizdek, bu yerda Return Type noaniq. Bu muammoni chetlash uchun ApiPaginatedResponse uchun schema ga title xususiyatini qo'shishingiz mumkin:

1export const ApiPaginatedResponse = <TModel extends Type<any>>(
2  model: TModel,
3) => {
4  return applyDecorators(
5    ApiOkResponse({
6      schema: {
7        title: `PaginatedResponseOf${model.name}`,
8        allOf: [
9          // ...
10        ],
11      },
12    }),
13  );
14};

Endi klient generatori natijasi quyidagicha bo'ladi:

1// Angular
2findAll(): Observable<PaginatedResponseOfCatDto>