Ghi lại các API NestJS với Swagger

Swagger là một khuôn khổ mã nguồn mở, miễn phí để tạo tài liệu API tương tác và thân thiện với người dùng. Nó tạo ra các trang web tương tác cho phép bạn kiểm tra một API với nhiều đầu vào khác nhau.

Swagger hỗ trợ cả tải trọng JSON và XML. Tài liệu mà nó tạo ra phù hợp cho các nhà phát triển và không phải nhà phát triển sử dụng.

Bạn có thể ghi lại các API web NestJS của mình qua Swagger bằng cách sử dụng các trình trang trí đơn giản mà không cần phải rời khỏi IDE của mình.

Bước 1: Tạo API

Trước khi bắt đầu, bạn phải tạo một API demo mà Swagger sẽ tạo tài liệu cho nó.

Bạn sẽ tạo API demo từ đầu bằng NestJS CLI.

Đầu tiên, tạo một dự án NestJS mới bằng cách chạy:

nest new <name-of-your-project>

Sau đó, thay đổi thư mục thành dự án đã tạo của bạn bằng cách chạy:

cd <name-of-your-project>

Tiếp theo, bạn sẽ tạo một REST API với CLI bằng cách chạy:

nest generate resource demo 

Bạn sẽ thấy một truy vấn hỏi, “Bạn sử dụng lớp truyền tải nào?” lựa chọn API REST.

Bạn sẽ thấy một truy vấn khác hỏi, “Bạn có muốn tạo điểm nhập CRUD không?” Loại hình Y va đanh đi vào.

Lệnh trên tạo API REST đầy đủ chức năng với điểm cuối CRUD và không có tệp kiểm tra đơn vị. Vì thế – không có thông số kỹ thuật cờ trong lệnh trên.

Bước 2: Cài đặt Swagger

Cài đặt Swagger và thư viện Express UI của nó bằng cách chạy:

npm install 

Bước 3: Định cấu hình Swagger

Trong của bạn main.ts tập tin, nhập khẩu SwaggerModule và DocumentBuilder từ @ nestjs / swagger.

DocumentBuilder hỗ trợ cấu trúc một tài liệu cơ sở. Nó cung cấp một số phương pháp mà bạn có thể xâu chuỗi lại với nhau và đóng lại với xây dựng phương pháp.

Các phương pháp này cho phép cấu hình nhiều thuộc tính, chẳng hạn như tiêu đề, mô tả và phiên bản.

Tạo một cấu hình biến đối tượng trong của bạn bootstrap chức năng như vậy:

const config = new DocumentBuilder()
.setTitle('Demo API')
.setDescription('A Demo API with CRUD functionality')
.setVersion('1.0')
.build();

Một phiên bản mới của DocumentBuilder tạo một tài liệu cơ sở phù hợp với Đặc tả OpenAPI. Sau đó, bạn có thể sử dụng phiên bản này để đặt tiêu đề, mô tả và phiên bản thông qua các phương pháp thích hợp của chúng.

Tiếp theo, bạn sẽ cần tạo một tài liệu hoàn chỉnh với tất cả các tuyến HTTP được xác định bằng tài liệu cơ sở.

Để làm điều này, hãy gọi createDocument trên SwaggerModule. createDocument chấp nhận hai đối số: một cá thể ứng dụng và một đối tượng tùy chọn Swagger. Lưu trữ kết quả của cuộc gọi này trong một biến để sử dụng sau này:

const document = SwaggerModule.createDocument(app, config);

Tiếp theo, hãy gọi cho thành lập trên SwaggerModule. Phương thức thiết lập có ba đối số:

1. Đường dẫn giao diện người dùng Swagger. Theo quy ước, bạn có thể sử dụng “api”.
2. Một trường hợp ứng dụng
3. Toàn bộ tài liệu

Ngoài ra, phương pháp thiết lập có một đối tượng tùy chọn tùy chọn. Xem tài liệu của NestJS về các tùy chọn tài liệu Swagger để tìm hiểu thêm về nó.

Như vậy:

SwaggerModule.setup('api', app, document);

Khởi động ứng dụng của bạn và đi tới http: // localhost: / api

Bạn sẽ thấy giao diện người dùng Swagger được hiển thị trên trang.

Hình ảnh trên là chế độ xem mặc định của giao diện người dùng Swagger, với tất cả các tuyến HTTP trong bộ điều khiển của bạn được xác định. Bạn sẽ cần phải tùy chỉnh nó để phù hợp với chức năng API của mình.

Bước 4: Tùy chỉnh thuộc tính API

Theo mặc định, Swagger đặt tiền tố cho toàn bộ phần tuyến HTTP bằng một tiêu đề có nội dung “mặc định”. Bạn có thể thay đổi điều này bằng cách chú thích lớp bộ điều khiển của bạn với @ApiTags trang trí và chuyển thẻ ưa thích của bạn làm đối số.

Như vậy:

import { ApiTags } from '@nestjs/swagger';
@ApiTags('Demo')
@Controller('demo')
export class DemoController {

Phần Lược đồ chứa các đối tượng Truyền dữ liệu trong API của bạn. Hiện tại, giao diện người dùng không bao gồm thuộc tính nào của chúng.

Để khai báo thuộc tính của chúng trong giao diện người dùng, chỉ cần thêm trình trang trí. Chú thích từng thuộc tính bắt buộc với @ApiProperty người trang trí. Chú thích các thuộc tính tùy chọn với @ApiPropertyOptional người trang trí.

Ví dụ:

import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
export class CreateDemoDto {
@ApiProperty({
type: String,
description: 'This is a required property',
})
property: string;
@ApiPropertyOptional({
type: String,
description: 'This is an optional property',
})
optionalProperty: string;
}

Mỗi trình trang trí @ApiProperty và @ApiPropertyOptional chấp nhận một đối tượng tùy chọn. Đối tượng đó mô tả thuộc tính sau đây.

Lưu ý rằng đối tượng tùy chọn sử dụng JavaScript, không phải TypeScript. Do đó, các khai báo kiểu JavaScript (tức là Chuỗi, không phải chuỗi).

Chú thích các thuộc tính của đối tượng Truyền dữ liệu thêm một ví dụ về dữ liệu mong đợi vào phần Lược đồ. Nó cũng cập nhật tuyến HTTP được liên kết với một ví dụ về dữ liệu mong đợi.

Bước 5: Đặt phản hồi API

Trong lớp bộ điều khiển của bạn, hãy sử dụng @ApiResponse trình trang trí để ghi lại tất cả các phản hồi tiềm năng cho mỗi tuyến HTTP. Đối với mỗi điểm cuối, các trình trang trí @ApiResponse khác nhau mô tả loại phản hồi mong đợi.

Chúng tôi đã giải thích các phản hồi HTTP phổ biến, trong trường hợp bạn không hiểu ý nghĩa của chúng.

Trình trang trí @ApiResponse chấp nhận một đối tượng tùy chọn mô tả phản hồi.

Các phản hồi POST phổ biến

Đối với một yêu cầu ĐĂNG, các phản hồi có thể bao gồm:

• ApiCreateResponsecho 201 phản hồi đã tạo thành công.
• ApiUnprocessableEnityResponseđối với 422 phản hồi đối tượng không thể xử lý không thành công.
• ApiForbiddenResponsecho 403 câu trả lời bị cấm.

Ví dụ:

@Post()
@ApiCreatedResponse({ description: 'Created Succesfully' })
@ApiUnprocessableEntityResponse({ description: 'Bad Request' })
@ApiForbiddenResponse({ description: 'Unauthorized Request' })
create(@Body() createDemoDto: CreateDemoDto) {
return this.demoService.create(createDemoDto);
}

Phản hồi GET chung

Đối với các yêu cầu GET, các phản hồi có thể bao gồm:

• ApiOkResponsecho 200 câu trả lời ok.
• ApiForbiddenResponsecho 403 câu trả lời bị cấm.
• ApiNotFoundResponsecho 404 câu trả lời không tìm thấy.

Ví dụ:

@Get()
@ApiOkResponse({ description: 'The resources were returned successfully' })
@ApiForbiddenResponse({ description: 'Unauthorized Request' })
findAll() {
return this.demoService.findAll();
}
@Get(':id')
@ApiOkResponse({ description: 'The resource was returned successfully' })
@ApiForbiddenResponse({ description: 'Unauthorized Request' })
@ApiNotFoundResponse({ description: 'Resource not found' })
findOne(@Param('id') id: string) {
return this.demoService.findOne(+id);
}

Các phản hồi PATCH và CẬP NHẬT thông thường

Đối với các yêu cầu PATCH và UPDATE, các phản hồi có thể bao gồm:

• ApiOkResponsecho 200 câu trả lời ok.
• ApiNotFoundResponsecho 404 câu trả lời không tìm thấy.
• ApiUnprocessibleEntityResponseđối với 422 phản hồi đối tượng không thể xử lý không thành công.
• ApiForbiddenResponsecho 403 câu trả lời bị cấm.

Ví dụ:

@Patch(':id')
@ApiOkResponse({ description: 'The resource was updated successfully' })
@ApiNotFoundResponse({ description: 'Resource not found' })
@ApiForbiddenResponse({ description: 'Unauthorized Request' })
@ApiUnprocessableEntityResponse({ description: 'Bad Request' })
update(@Param('id') id: string, @Body() updateDemoDto: UpdateDemoDto) {
return this.demoService.update(+id, updateDemoDto);
}

Các phản hồi DELETE phổ biến

Đối với các yêu cầu XÓA, các phản hồi có thể bao gồm:

• ApiOkResponsecho 200 câu trả lời ok.
• ApiForbiddenResponsecho 403 câu trả lời bị cấm.
• ApiNotFoundResponsecho 404 câu trả lời không tìm thấy.

Ví dụ:

@Delete(':id')
@ApiOkResponse({ description: 'The resource was returned successfully' })
@ApiForbiddenResponse({ description: 'Unauthorized Request' })
@ApiNotFoundResponse({ description: 'Resource not found' })
remove(@Param('id') id: string) {
return this.demoService.remove(+id);
}

Những người trang trí này điền vào tài liệu của bạn những câu trả lời có thể. Bạn có thể xem chúng bằng cách sử dụng menu thả xuống dọc theo mỗi tuyến đường.

Xem tài liệu của bạn

Khi thiết lập xong, bạn có thể xem tài liệu của mình trên localhost: / api. Nó sẽ hiển thị tài liệu API tương tác của bạn.

Các yếu tố cần thiết của tài liệu API Swagger là mô tả, loại phản hồi và định nghĩa lược đồ. Đây là những điều cơ bản cần thiết để tạo tài liệu API tốt.