Cách thiết lập Enumeration cho trường (ví dụ: chuỗi, mảng, v.v.) trong Apidog

Chào bạn! Nếu bạn đang tìm hiểu về thiết kế API với Apidog và muốn làm cho giao diện của mình trở nên rõ ràng, việc thiết lập các kiểu liệt kê (hay enums) là điều cần thiết. Enums cho phép bạn định nghĩa một tập hợp các giá trị cố định cho một trường—chẳng hạn như “active,” “frozen,” hoặc “deleted” cho trạng thái người dùng—đảm bảo các nhà phát triển chỉ chọn từ những tùy chọn đó. Điều này ngăn ngừa các lỗi khó chịu và giữ cho tài liệu API của bạn sắc nét. Trong hướng dẫn trò chuyện này, chúng ta sẽ khám phá cách thiết lập các kiểu liệt kê cho chuỗi, mảng và nhiều hơn nữa trong Apidog, sử dụng giao diện người dùng trực quan và các tính năng được hỗ trợ bởi AI của nó. Dù bạn là người mới bắt đầu hay một nhà phát triển có kinh nghiệm, bạn sẽ thiết lập các kiểu liệt kê Apidog như một chuyên gia trong thời gian ngắn. Hãy bắt đầu!

💡

Bạn muốn một công cụ Kiểm thử API tuyệt vời tạo ra Tài liệu API đẹp mắt?

Bạn muốn một nền tảng tích hợp, Tất cả trong Một để Đội ngũ Phát triển của bạn làm việc cùng nhau với năng suất tối đa?

Apidog đáp ứng mọi yêu cầu của bạn và thay thế Postman với mức giá phải chăng hơn nhiều!

nút

Tại sao nên sử dụng kiểu liệt kê trong Apidog?

Các kiểu liệt kê giống như rào chắn bảo vệ cho các trường API của bạn. Hãy tưởng tượng một trường “trạng thái người dùng” mà chỉ có “active,” “frozen,” hoặc “deleted” là hợp lệ. Nếu không có enum, các nhà phát triển có thể vô tình truyền “inactive” hoặc “banned,” khiến API của bạn gặp lỗi. Bằng cách thiết lập kiểu liệt kê Apidog, bạn liệt kê rõ ràng các giá trị được phép, làm cho tài liệu của bạn rõ ràng và giảm lỗi. Hơn nữa, tính năng dữ liệu giả lập (Mock data) của Apidog tự động tuân thủ các enum này, tạo ra dữ liệu kiểm thử phù hợp với quy tắc của bạn. Dù đó là một chuỗi như “pending” hay một mảng các quyền cụ thể, enum giúp hợp lý hóa việc cộng tác và giữ cho API của bạn mạnh mẽ.

Apidog, một nền tảng mạnh mẽ để thiết kế, gỡ lỗi và kiểm thử API, hỗ trợ các enum cho nhiều loại dữ liệu khác nhau, bao gồm chuỗi, số nguyên, số thực và mảng. Bạn thậm chí có thể thêm mô tả cho mỗi giá trị để tăng cường sự rõ ràng. Hãy cùng tìm hiểu cách thiết lập chúng, từ các chuỗi cơ bản đến các mảng phức tạp, và khám phá cách AI và các mô hình có thể tái sử dụng giúp cuộc sống của bạn dễ dàng hơn.

Thiết lập các kiểu liệt kê cơ bản trong Apidog

Hãy bắt đầu với trường hợp đơn giản nhất: thiết lập kiểu liệt kê cho một trường chuỗi hoặc số, như trạng thái người dùng hoặc trạng thái đơn hàng. Đây là cách thực hiện:

Mở Trình chỉnh sửa Giao diện:

Trong Apidog, điều hướng đến dự án của bạn và mở giao diện (điểm cuối) bạn đang làm việc. Tìm trường bạn muốn giới hạn, chẳng hạn như user_status trong phần thân yêu cầu hoặc phản hồi.

2. Chọn Kiểu dữ liệu:

Trong cài đặt của trường, chọn kiểu dữ liệu từ danh sách thả xuống—thường là string (ví dụ: cho “active”), integer, hoặc number. Ví dụ, chọn string cho user_status.

3. Truy cập Cài đặt Nâng cao:

Nhấp vào nút Cài đặt Nâng cao bên cạnh kiểu trường. Thao tác này sẽ mở một bảng điều khiển nơi bạn có thể cấu hình enum.

4. Thêm Giá trị Liệt kê:

Trong phần Giá trị Liệt kê, nhập các giá trị được phép của bạn, mỗi giá trị một dòng. Đối với user_status, bạn có thể thêm:
active (Mô tả: “Người dùng đang hoạt động và có thể đăng nhập”)
frozen (Mô tả: “Tài khoản người dùng bị tạm khóa”)
deleted (Mô tả: “Tài khoản người dùng đã bị xóa vĩnh viễn”)
Tùy chọn, thêm mô tả cho mỗi giá trị để làm cho tài liệu rõ ràng hơn.

5. Lưu và Kiểm tra Tài liệu:

Lưu các thay đổi của bạn. Trong tài liệu API, Apidog sẽ hiển thị các giá trị này là các tùy chọn hợp lệ duy nhất cho trường. Các thành viên trong nhóm sẽ thấy một cái gì đó như: “user_status: Phải là một trong [active, frozen, deleted].”

Khi gỡ lỗi trong Apidog, bạn có thể chọn trực tiếp các giá trị enum này từ một danh sách thả xuống, đảm bảo các yêu cầu kiểm thử của bạn hợp lệ. Đó là một cách đơn giản để giữ cho mọi người thống nhất!

Mẹo chuyên nghiệp: Sử dụng tính năng Chỉnh sửa hàng loạt trong bảng enum để dán nhiều giá trị cùng một lúc, tiết kiệm thời gian cho các danh sách dài.

Xử lý kiểu liệt kê mảng trong Apidog

Các kiểu liệt kê mảng phức tạp hơn một chút nhưng cực kỳ hữu ích cho các trường như quyền người dùng hoặc tọa độ. Apidog hỗ trợ hai loại enum mảng: giới hạn các phần tử mảng riêng lẻ hoặc giới hạn toàn bộ mảng theo các tổ hợp cụ thể. Hãy cùng phân tích.

Tình huống 1: Giới hạn giá trị phần tử mảng

Giả sử bạn có một trường permissions là một mảng chuỗi, trong đó mỗi chuỗi phải là một trong “read,” “write,” hoặc “delete.” Các mảng hợp lệ có thể là ["read"], ["write", "delete"], hoặc ["read", "write", "delete"]. Đây là cách thiết lập:

Đặt Trường là Kiểu Mảng:

Trong trình chỉnh sửa giao diện, đặt trường (ví dụ: permissions) thành kiểu mảng.

2. Cấu hình Kiểu Phần tử con:

Trong cài đặt mảng, bạn sẽ thấy tùy chọn Kiểu Phần tử con. Chọn string (hoặc một kiểu khác như integer).

3. Thêm Giá trị Enum:

Nhấp vào Cài đặt Nâng cao cho phần tử con. Trong phần Giá trị Liệt kê, thêm:
read (Mô tả: “Quyền truy cập chỉ đọc”)
write (Mô tả: “Quyền ghi”)
delete (Mô tả: “Quyền xóa”)

4. Tùy chọn: Buộc tính duy nhất:

Trong cài đặt nâng cao của mảng, bật Tất cả các phần tử phải là duy nhất để ngăn chặn các bản sao (ví dụ: ["read", "read"] trở nên không hợp lệ).

5. Lưu và Kiểm thử:

Lưu, và tài liệu sẽ hiển thị các phần tử của mảng bị giới hạn bởi các giá trị này. Dữ liệu giả lập sẽ tạo ra các mảng như ["read", "write"], tuân thủ các quy tắc enum và tính duy nhất.

Ngoài ra, bạn có thể chỉnh sửa JSON Schema thủ công trong tab Cài đặt Nâng cao:

{
  "type": "array",
  "items": {
    "type": "string",
    "enum": ["read", "write", "delete"]
  },
  "uniqueItems": true
}

Điều này đảm bảo mọi phần tử trong mảng tuân thủ enum.

Tình huống 2: Giới hạn toàn bộ giá trị mảng

Đôi khi, bạn muốn toàn bộ mảng là một trong số ít các tổ hợp cố định, chẳng hạn như trường coordinate chỉ có thể là [0, 0] hoặc [100, 100]. Đây là cách thực hiện:

Đặt Trường là Kiểu Mảng:

Chọn array cho trường (ví dụ: coordinate).

2. Chỉnh sửa JSON Schema:

Trong Cài đặt Nâng cao, chuyển sang trình chỉnh sửa JSON Schema và nhập:

{
  "type": "array",
  "enum": [
    [0, 0],
    [100, 100]
  ]
}

Điều này giới hạn trường chỉ đúng với các mảng này—không có tổ hợp nào khác như [0, 100] được phép.

3. Lưu và Xác minh:

Lưu, và tài liệu sẽ liệt kê [0, 0] và [100, 100] là các giá trị hợp lệ duy nhất. Dữ liệu giả lập sẽ chọn ngẫu nhiên một trong các mảng này.

Cách tiếp cận này ít phổ biến hơn nhưng mạnh mẽ cho các trường hợp sử dụng cụ thể, như cài đặt được xác định trước hoặc cấu trúc dữ liệu cố định.

Sử dụng AI để đơn giản hóa việc thiết lập kiểu liệt kê

Viết JSON Schema cho các enum phức tạp, đặc biệt là mảng, có thể cảm thấy như đang vật lộn với cú pháp. May mắn thay, tính năng AI của Apidog ở đây để cứu vãn tình hình! Nó cho phép bạn mô tả các yêu cầu enum của mình bằng ngôn ngữ tự nhiên, và nó sẽ tạo ra cấu hình chính xác.

Bật AI trong Apidog:

Truy cập Cài đặt Nhóm > Tính năng AI và bật hỗ trợ AI. Kiểm tra tài liệu trợ giúp của Apidog để biết chi tiết.

2. Mô tả Nhu cầu của bạn:

Trong trình chỉnh sửa giao diện, mở bảng trò chuyện AI và gõ một cái gì đó như:

coordinate[1, 2][3, 4]

Hoặc đối với một chuỗi: “Giới hạn status thành pending, paid, hoặc completed.”

3. Xem trước và Áp dụng:

AI tạo ra JSON Schema, ví dụ:

{
  "type": "array",
  "enum": [
    [1, 2],
    [3, 4]
  ]
}

Xem lại kết quả, sau đó nhấp vào Áp dụng để thêm nó vào trường của bạn.

4. Kiểm thử:

Kiểm tra tài liệu để đảm bảo enum chính xác. Hãy thử gỡ lỗi với các giá trị enum trong giao diện của Apidog.

AI là một cứu tinh cho các schema phức tạp hoặc khi bạn không chắc chắn về cú pháp JSON. Nó nhanh hơn việc tìm kiếm trên Google và đảm bảo độ chính xác.

Dữ liệu giả lập và kiểu liệt kê

Một trong những tính năng tuyệt vời nhất của Apidog là cách nó tích hợp các enum với dữ liệu giả lập (Mock data). Khi bạn thiết lập một enum, dịch vụ Mock của Apidog tự động tạo dữ liệu kiểm thử tuân thủ các giới hạn của bạn. Ví dụ:

Enum chuỗi: Nếu status bị giới hạn thành ["active", "frozen", "deleted"], dữ liệu giả lập sẽ chọn ngẫu nhiên một trong các giá trị này.
Enum mảng với các phần tử duy nhất: Đối với một mảng permissions với ["read", "write", "delete"] và tính duy nhất được bật, bạn có thể nhận được ["read", "write"] nhưng không bao giờ là ["read", "read"].
Enum mảng cố định: Một trường coordinate với [[0, 0], [100, 100]] sẽ chỉ trả về một trong các mảng chính xác đó.

Điều này đảm bảo dữ liệu kiểm thử của bạn phù hợp với thông số kỹ thuật API của bạn, giúp việc gỡ lỗi và cộng tác suôn sẻ hơn. Để bật dữ liệu giả lập, bật tùy chọn Mock trong trình chỉnh sửa giao diện và xem trước kết quả.

Định nghĩa các mô hình kiểu liệt kê có thể tái sử dụng

Nếu cùng một enum xuất hiện trên nhiều điểm cuối—như user_status trong các API tạo, cập nhật và liệt kê người dùng—việc định nghĩa lại nó mỗi lần là một cực hình. Apidog cho phép bạn tạo các mô hình dữ liệu có thể tái sử dụng để giữ mọi thứ nhất quán.

Tạo một Mô hình Dữ liệu:

Truy cập Mô hình Dữ liệu trong dự án Apidog của bạn.
Nhấp vào Mô hình Mới, đặt tên cho nó (ví dụ: UserStatusEnum), và đặt nút gốc là string.
Trong Cài đặt Nâng cao, thêm các giá trị enum như active, frozen, deleted với mô tả tùy chọn.

2. Tham chiếu Mô hình:

Trong bất kỳ giao diện nào, đặt kiểu của trường là Tham chiếu và chọn UserStatusEnum.

3. Cập nhật một lần, đồng bộ mọi nơi:

Nếu bạn cần thêm một trạng thái mới (ví dụ: suspended), hãy cập nhật mô hình UserStatusEnum, và tất cả các điểm cuối tham chiếu sẽ tự động cập nhật.

Cách tiếp cận này tiết kiệm thời gian và đảm bảo tính nhất quán trên toàn bộ dự án của bạn. Nó hoàn hảo cho các nhóm nơi nhiều nhà phát triển dựa vào cùng một enum.

Khắc phục sự cố thường gặp về kiểu liệt kê

Enum không hiển thị trong tài liệu? Lưu giao diện và làm mới trang tài liệu. Đảm bảo trường được đánh dấu là Bắt buộc nếu cần.
Dữ liệu giả lập bỏ qua Enum? Kiểm tra xem các giá trị enum có được đặt đúng trong Cài đặt Nâng cao hoặc JSON Schema hay không. Bật/tắt tùy chọn Mock.
Lỗi Enum mảng? Đối với enum cấp phần tử, đảm bảo kiểu phần tử con được đặt đúng. Đối với các mảng cố định, hãy xác minh cú pháp JSON Schema.
AI không tạo Schema? Làm rõ lời nhắc của bạn (ví dụ: “Giới hạn ở các mảng chính xác”) và đảm bảo AI được bật trong Cài đặt Nhóm.

Tại sao kiểu liệt kê làm cho Apidog nổi bật

Kiểu liệt kê Apidog là một yếu tố thay đổi cuộc chơi trong thiết kế API. Chúng làm rõ các giới hạn trường, giảm lỗi và nâng cao khả năng đọc tài liệu. Tính năng AI đơn giản hóa các thiết lập phức tạp, trong khi các mô hình có thể tái sử dụng đảm bảo tính nhất quán. Việc tích hợp dữ liệu giả lập có nghĩa là các kiểm thử của bạn luôn tuân thủ thông số kỹ thuật. So với các công cụ như Postman, trình chỉnh sửa trực quan và AI của Apidog giúp việc thiết lập enum trực quan hơn, đặc biệt đối với các mảng. Người dùng ca ngợi Apidog vì “biến tài liệu API thành không thể sai sót,” và với sự hỗ trợ enum, thật dễ hiểu tại sao.

Kết luận

Thiết lập kiểu liệt kê Apidog thật dễ dàng, dù bạn đang giới hạn chuỗi, số hay mảng. Từ trình chỉnh sửa trực quan đến việc tạo JSON Schema được hỗ trợ bởi AI, Apidog làm cho các API của bạn mạnh mẽ và thân thiện với nhà phát triển. Hãy thử tạo một mô hình enum có thể tái sử dụng hoặc sử dụng AI để tăng tốc mọi thứ, và chia sẻ mẹo của bạn trong phần bình luận. Hãy cùng nhau làm cho thiết kế API mượt mà hơn!

💡

nút