Thành phần

Thông thường trong thiết kế API, mặc dù các phản hồi 200 OK thành công thường khác nhau giữa nhiều endpoint do nhu cầu dữ liệu đầu ra riêng biệt, các phản hồi lỗi như 400 Bad Request và 404 Not Found có xu hướng nhất quán giữa các endpoint khác nhau.

Apidog xử lý điểm chung này một cách thông minh bằng tính năng Thành phần phản hồi, cho phép tái sử dụng các phản hồi lỗi đã được định nghĩa trước, giúp quy trình tài liệu hóa API hiệu quả hơn và hành vi API nhất quán hơn.

Khả năng tương thích với OAS

Tính năng Thành phần phản hồi trong Apidog tương thích với Components trong OAS.

Thêm Thành phần phản hồi

Trong cây thư mục bên trái của mô-đun APIs, điều hướng đến phần Components, sau đó nhấp vào New Response bên dưới Responses để tạo một thành phần phản hồi mới.

Việc tạo một thành phần phản hồi tương tự như chỉ định phần phản hồi khi định nghĩa một endpoint, bao gồm mã trạng thái HTTP, Content type, Schema và Examples. Để xem hướng dẫn chi tiết, hãy tham khảo phần Response trong Endpoint Basics.

Tính năng độc đáo của Thành phần phản hồi

Được thêm mặc định vào các endpoint mới: Khi được chọn là "Yes", thành phần này sẽ tự động được bao gồm mặc định trong tất cả các endpoint mới được thêm vào dự án.

INFO

Các endpoint hiện có không bị ảnh hưởng bởi thiết lập này.

Tham chiếu Thành phần phản hồi

Trong phần Response của một endpoint, bạn có thể tham chiếu một thành phần phản hồi đã được định nghĩa trước.

Các điểm chính về thành phần được tham chiếu:

Không thể sửa đổi các thành phần phản hồi được tham chiếu trong endpoint. Bạn phải thực hiện thay đổi đối với thành phần phản hồi gốc. Mọi sửa đổi được thực hiện sẽ ảnh hưởng đến tất cả các endpoint đang tham chiếu thành phần này.

Nếu bạn muốn sửa đổi một thành phần phản hồi đã được tham chiếu trong một endpoint, bạn có thể Dereference thành phần đó. Việc bỏ tham chiếu sẽ chuyển phản hồi thành một phản hồi thông thường có thể chỉnh sửa, và các thay đổi đối với thành phần phản hồi sẽ không còn ảnh hưởng đến phản hồi này nữa.

Trong một endpoint, một thành phần chỉ có thể được tham chiếu một lần; nhiều phiên bản của cùng một thành phần không thể cùng tồn tại trong cùng một endpoint.

Thao tác hàng loạt

Bạn có thể Add hàng loạt các thành phần phản hồi hiện có vào các endpoint đã chọn, hoặc Remove hàng loạt thành phần này khỏi các endpoint đã chọn.

Lưu ý:

Nếu endpoint đã chọn đã bao gồm thành phần phản hồi này, thành phần đó sẽ không được thêm lại.

Nếu endpoint đã chọn không chứa thành phần phản hồi này, thao tác xóa sẽ không có hiệu lực.

Mẫu phản hồi mặc định

Nhiều công ty có cấu trúc chuẩn hóa cho các phản hồi của họ. Trong những trường hợp như vậy, bạn có thể tận dụng Mẫu phản hồi mặc định để duy trì cấu trúc cố định của công ty làm mẫu phản hồi mặc định.

Trong cây thư mục bên trái dưới phần Components, bạn có thể truy cập và sử dụng tính năng Default Response Template.

Khi một endpoint mới được tạo, nội dung của mẫu này được sử dụng làm phản hồi ban đầu.

Đặc điểm chính:

Các thay đổi được thực hiện đối với mẫu phản hồi mặc định sẽ chỉ ảnh hưởng đến các endpoint mới, còn các endpoint hiện có sẽ không bị ảnh hưởng.

Chỉ tồn tại một mẫu phản hồi mặc định duy nhất, không thể thêm hoặc xóa.

Mẫu phản hồi mặc định ban đầu là một 200 Success Response với Content type là JSON và cấu trúc dữ liệu là một nút Object rỗng.

Câu hỏi thường gặp

H: Tôi có thể sử dụng một thành phần phản hồi làm phản hồi mặc định không?

Đ: Không, các thành phần phản hồi được dùng cho các phản hồi lỗi chung như 400, 404 và các mã trạng thái tương tự. Nếu bạn cần sử dụng một phản hồi mặc định cố định, vui lòng sử dụng mẫu phản hồi mặc định.

Thêm Thành phần phản hồi#

Tính năng độc đáo của Thành phần phản hồi#

Tham chiếu Thành phần phản hồi#

Thao tác hàng loạt#

Mẫu phản hồi mặc định#

Câu hỏi thường gặp#

Thêm Thành phần phản hồi

Tính năng độc đáo của Thành phần phản hồi

Tham chiếu Thành phần phản hồi

Thao tác hàng loạt

Mẫu phản hồi mặc định

Câu hỏi thường gặp