Bạn đã định nghĩa một endpoint và muốn gọi nó từ ứng dụng của mình. Phần tẻ nhạt là chuyển đổi đặc tả thành mã hoạt động: URL chính xác, các tiêu đề, mã thông báo xác thực, chuỗi truy vấn, tất cả được kết nối vào một lệnh gọi requests hoặc fetch. Sao chép sai một ký tự và bạn sẽ mất hai mươi phút tự hỏi tại sao máy chủ trả về mã 401.
Bạn không cần phải viết tay những đoạn mã trùng lặp đó. Nếu API của bạn được thiết kế trong Apidog, nền tảng sẽ đọc đặc tả endpoint của bạn và cung cấp cho bạn một đoạn mã yêu cầu sẵn sàng dán bằng ngôn ngữ bạn đang làm việc: cURL để kiểm tra nhanh trong terminal, Python requests cho một script, JavaScript fetch hoặc Axios cho frontend. Hướng dẫn này sẽ chỉ cho bạn cách tạo mã đó từ một endpoint thực tế, khi nào nên gửi yêu cầu trước để đoạn mã mang theo các giá trị thực tế và cách giữ cho mã được tạo chính xác khi đặc tả của bạn thay đổi. Nếu bạn muốn có cái nhìn rộng hơn về các lựa chọn, bài tổng hợp của chúng tôi về các công cụ tạo mã API sẽ cung cấp cho bạn cái nhìn tổng quan hơn; ở đây chúng ta sẽ thực hành với trình tạo tích hợp sẵn.
Ý tưởng dựa trên một đặc tả là nguồn chân lý duy nhất, cùng nguyên tắc đằng sau OpenAPI Specification. Định nghĩa đúng một lần, và mã yêu cầu sẽ theo đó.
Trình tạo mã client thực sự làm gì
Apidog biến một định nghĩa endpoint thành một đoạn mã yêu cầu cho mỗi biến thể ngôn ngữ. Chỉ nó vào GET /orders, chọn Python và thư viện Requests, và nó sẽ viết lệnh gọi đến đường dẫn đó với các tiêu đề và tham số mà đặc tả của bạn khai báo. Đó là một trình tạo yêu cầu: nó tạo ra mã cho một lệnh gọi, theo cú pháp của ngôn ngữ và thư viện HTTP bạn đã chọn.
Thiết lập đúng kỳ vọng về một điểm. Tính năng này tạo ra mã yêu cầu hoặc mã client cho một endpoint, chứ không phải một SDK đầy đủ hay một gói thư viện client có phiên bản. Nếu bạn cần một dòng curl, một khối Python requests, hoặc một đoạn mã JS fetch để chèn vào mã của bạn, đó là những gì bạn nhận được. Tài liệu không mô tả một trình tạo thư viện đầy đủ, vì vậy đừng mong đợi một SDK được gõ có thể tải xuống với các mô hình và công cụ hỗ trợ phân trang được tích hợp sẵn.
Điều này kết hợp tự nhiên với quy trình phát triển API thiết kế trước. Bạn định nghĩa hợp đồng, tạo mã yêu cầu trực tiếp từ đó, và mọi người tiêu dùng đều bắt đầu từ cùng một định nghĩa chính xác thay vì một ảnh chụp màn hình được dán vào Slack.
Hai cách để mở trình tạo
Apidog cung cấp cho bạn hai điểm truy cập vào cùng một tính năng. Sử dụng cái nào phù hợp với vị trí bạn đang ở.
Cách thứ nhất là từ tài liệu. Mở tab Tài liệu cho API của bạn, sau đó nhấp vào nút Tạo mã Client ở phía bên phải. Đây là con đường nhanh nhất khi bạn đang đọc tài liệu của một endpoint và muốn có lệnh gọi cho nó.
Cách thứ hai là từ trình chạy. Trong tab Chạy của API, nhấp vào biểu tượng mã </>. Nút này nằm cạnh nơi bạn xây dựng và gửi yêu cầu, vì vậy đó là lựa chọn tự nhiên khi bạn đã kiểm thử lệnh gọi.
Cả hai đều mở cùng một bảng điều khiển. Từ đó bạn chọn một ngôn ngữ và một biến thể, và Apidog sẽ viết đoạn mã.
Tạo một lệnh gọi client Python cho GET /orders
Đây là quy trình đầy đủ với một endpoint thực tế: một lệnh gọi GET /orders liệt kê các đơn hàng của khách hàng, được lọc theo trạng thái và phân trang.
Bước 1: mở endpoint và chọn ngôn ngữ của bạn
Mở tab Tài liệu cho endpoint và nhấp vào Tạo mã Client. Trong bảng điều khiển, chọn mục tiêu của bạn. Apidog hỗ trợ một danh sách dài các ngôn ngữ và biến thể, vì vậy bạn có thể khớp chính xác với stack của mình:
- Shell: cURL, cURL-Windows, Httpie, wget, PowerShell
- JavaScript: Fetch, Axios, jQuery, XHR, Native, Request, Unirest
- Python: http.client, Requests
- Java: Unirest, OkHttp
- Go: Native
- PHP: cURL, Guzzle, pecl_http, HTTP_Request2
- Khác: Swift (URLSession), C (libcurl), C#, Objective-C, Ruby, OCaml, Dart, R, cộng với tùy chọn HTTP thô
Đối với ví dụ này, chọn Python và biến thể Requests. Apidog tạo ra thứ gì đó như thế này từ đặc tả:
import requests
url = "https://api.example.com/orders"
querystring = {"status": "shipped", "page": "1"}
headers = {"Accept": "application/json"}
response = requests.get(url, headers=headers, params=querystring)
print(response.json())
Sao chép nó, thả nó vào script của bạn, và nó là một lệnh gọi hoạt động. Đó là con đường thiết kế trước: đoạn mã phản ánh chính xác những gì endpoint của bạn khai báo.
Bước 2: hiểu những gì đoạn mã chỉ có trong đặc tả bao gồm
Có một điều cần hiểu trước khi bạn dán. Mã được tạo trực tiếp từ đặc tả API chỉ bao gồm đặc tả API, không phải các giá trị tham số yêu cầu thực hoặc mã thông báo ủy quyền của bạn. Bạn nhận được hình dạng của lệnh gọi và bất kỳ giá trị ví dụ nào được định nghĩa trong đặc tả, nhưng không phải tiêu đề Authorization: Bearer ... trực tiếp mà bạn cần để thực sự truy cập một endpoint được bảo vệ.
Điều đó ổn cho một lệnh gọi không có xác thực hoặc khi bạn tự điền mã thông báo. Đối với một GET /orders được bảo vệ, bạn muốn các giá trị thực trong mã.
Bước 3: gửi yêu cầu trước để thu thập các giá trị thực
Để nhận một đoạn mã mang các giá trị tham số và thông tin ủy quyền thực tế, hãy gửi yêu cầu trước, sau đó đọc mã từ tab Yêu cầu Thực tế.
Nếu bạn đang làm việc theo hướng thiết kế trước, điều này rất dễ dàng. Định nghĩa endpoint trong tab Chỉnh sửa, nhấp vào tab Chạy, và các tham số yêu cầu sẽ tự động điền từ đặc tả. Nếu bạn muốn thiết lập thủ công (chế độ yêu cầu trước), hãy nhập các tham số yêu cầu thủ công trong tab Chạy. Dù bằng cách nào, hãy thêm mã thông báo xác thực của bạn, sau đó nhấp vào Gửi để truyền yêu cầu.
Sau khi nhận được phản hồi, chuyển sang tab Yêu cầu Thực tế và cuộn xuống để tìm mã client. Bây giờ đoạn mã được tạo bao gồm các giá trị cụ thể và tiêu đề xác thực đã thực sự được gửi:
import requests
url = "https://api.example.com/orders"
querystring = {"status": "shipped", "page": "1"}
headers = {
"Accept": "application/json",
"Authorization": "Bearer sk_live_51H8xY2..."
}
response = requests.get(url, headers=headers, params=querystring)
print(response.json())
Đó là sự khác biệt giữa hai con đường. Chế độ thiết kế trước tự động điền tham số từ đặc tả; chế độ yêu cầu trước cho phép bạn nhập chúng. Cả hai đều cung cấp cùng một đoạn mã Yêu cầu Thực tế sau khi bạn nhấp vào Gửi. Hãy coi một mã thông báo thực như mã ở trên là bí mật và giữ nó khỏi bất cứ thứ gì bạn cam kết vào git; sự cẩn trọng tương tự mà tài liệu của Stripe khuyến cáo cho các khóa trực tiếp cũng áp dụng ở đây.
Xử lý các phần thân yêu cầu cho POST và PUT
GET /orders không có phần thân, nhưng ngay khi bạn tạo mã cho một POST /orders hoặc một PUT /orders/{id}, bạn cần một phần thân yêu cầu trong đoạn mã. Apidog giúp bạn xây dựng một phần trong tab Chạy trước khi bạn tạo.
Đối với các phần thân JSON hoặc XML, bạn có hai nguồn. Sử dụng một ví dụ được định nghĩa trước từ đặc tả endpoint, hoặc nhấp vào Tự động tạo để tạo một cấu trúc phần thân khớp với schema của bạn. Menu thả xuống Tự động tạo cung cấp cho bạn hai chế độ:
- Ví dụ: chọn thủ công một ví dụ phần thân yêu cầu được định nghĩa trước.
- Tạo mỗi lần: tạo lại dữ liệu mỗi lần sử dụng, tuân theo các quy tắc mock thông minh để bạn nhận được các giá trị mới, hợp lệ theo schema mỗi lần.
Bạn có thể điều khiển cách dữ liệu được tạo thông qua các tùy chọn phụ Tùy chọn Tự động tạo: Sử dụng Giá trị Ví dụ trước, Sử dụng Giá trị Mặc định trước, Sử dụng Giá trị Mock, Chỉ tạo Tên trường, và Sử dụng Ví dụ Yêu cầu. Chọn Sử dụng Giá trị Ví dụ trước khi đặc tả của bạn có các ví dụ tốt và bạn muốn chúng được tôn trọng; chọn Sử dụng Giá trị Mock khi bạn muốn dữ liệu được tạo thực tế cho mỗi trường.
Một lưu ý về phiên bản: các tùy chọn Tự động tạo cho phần thân yêu cầu yêu cầu Apidog 2.7.0 trở lên. Nếu bạn không thấy chúng, hãy cập nhật ứng dụng. Một schema được chỉ định tốt với các ví dụ, loại bạn nhận được từ tự động tạo tài liệu API từ OpenAPI, sẽ giúp bước này tạo ra các phần thân sạch với gần như không cần chỉnh sửa thủ công.
Khi bạn cần một giá trị thay đổi theo từng yêu cầu, như một dấu thời gian mới hoặc một ID đơn hàng ngẫu nhiên, hãy chèn một giá trị động thay vì mã hóa cứng. Nhấp vào biểu tượng đũa thần bên cạnh hộp nhập tham số, hoặc sử dụng nút Chèn Giá trị Động bên trong phần thân yêu cầu JSON hoặc XML. Sau khi phần thân đã sẵn sàng, nhấp vào Gửi, sau đó đọc đoạn mã hoàn chỉnh từ tab Yêu cầu Thực tế như trước.
Khi nào sử dụng đoạn mã yêu cầu so với lệnh gọi mô hình nghiệp vụ
Một quyết định nhanh chóng: bạn nên sao chép bao nhiêu mã?
Sử dụng một đoạn mã yêu cầu đơn lẻ (cURL, fetch, một requests.get trần) khi bạn đang làm một công việc một lần. Gỡ lỗi tại sao một endpoint trả về mã 403, chia sẻ một lệnh gọi có thể tái tạo trong một ticket, chạy một kiểm tra nhanh trong terminal, hoặc dán một ví dụ vào tài liệu của riêng bạn. Nó tự chứa và không cần cấu trúc xung quanh.
Nghiêng về mã kiểu mô hình nghiệp vụ hoàn chỉnh hơn (khối Axios hoặc requests với các tiêu đề, tham số và xử lý phản hồi được bố trí) khi lệnh gọi nằm trong logic ứng dụng thực tế. Nếu GET /orders sẽ nằm trong một module dịch vụ được gọi từ ba nơi, bạn muốn phiên bản có cấu trúc mà bạn có thể gói trong một hàm, thêm xử lý lỗi và tái sử dụng. Trình tạo cung cấp cho bạn cả hai hình dạng tùy thuộc vào biến thể bạn chọn; khớp hình dạng với nơi mã sẽ tồn tại.
Nếu bạn đang gọi cùng một endpoint với cùng một xác thực trên toàn bộ dự án, thường thì việc tập trung các phần dùng chung sẽ sạch hơn. Hướng dẫn của chúng tôi về cách đặt tham số toàn cục trong Apidog chỉ ra cách định nghĩa các tiêu đề và biến một lần để mỗi lệnh gọi được tạo kế thừa chúng thay vì lặp lại mã thông báo trong mỗi đoạn mã.
Giữ mã được tạo chính xác với thói quen thiết kế trước
Mã được tạo chỉ đúng như đặc tả đằng sau nó. Thay đổi GET /orders để thêm một tham số truy vấn region và quên tạo lại, và đoạn mã đã sao chép của bạn sẽ bị sai một cách lặng lẽ. Cách khắc phục là coi đặc tả là thứ bạn duy trì, và mã là một đầu ra được dẫn xuất mà bạn tạo lại theo yêu cầu. Chế độ thiết kế trước của Apidog giữ cho định nghĩa có thẩm quyền để mã yêu cầu bạn tạo luôn phản ánh hợp đồng hiện tại, không phải một hợp đồng cũ.
Đối với cú pháp của chính các đoạn mã, tài liệu MDN về Fetch API là một tài liệu tham khảo vững chắc khi bạn muốn hiểu hoặc điều chỉnh các biến thể JavaScript mà Apidog tạo ra.
Tự động hóa quy trình làm việc với Apidog CLI
Việc tạo mã tự nó là một hành động GUI; bạn sao chép một đoạn mã từ một bảng điều khiển, và không có lệnh CLI riêng biệt nào phát ra mã client. Điều mà Apidog CLI làm tốt là giữ hai thứ xung quanh mà việc tạo mã phụ thuộc vào: một đặc tả cập nhật và các bài kiểm tra vượt qua chứng minh rằng client được tạo thực sự hoạt động.
Cài đặt nó bằng npm install -g apidog-cli (Node.js v16+) và xác thực:
apidog login --with-token <YOUR_ACCESS_TOKEN>
Nhập các thay đổi đặc tả mới để mã bạn tạo luôn cập nhật, và chạy kịch bản kiểm tra đã lưu để kiểm tra endpoint mà client của bạn gọi:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Ở đây -t là ID kịch bản kiểm tra, -e là ID môi trường, và -r là trình báo cáo (cli, html, hoặc junit). Kết nối điều này vào pipeline của bạn, theo cách mà hướng dẫn Apidog CLI GitHub Actions của chúng tôi trình bày, và mỗi lần push sẽ xác minh rằng GET /orders vẫn hoạt động như đặc tả đã hứa trước khi bất kỳ ai tạo lại client từ nó. CLI không viết mã client của bạn, nhưng nó bảo vệ hợp đồng mà mã đó được xây dựng trên.
Câu hỏi thường gặp
Mã được tạo có bao gồm khóa API và mã thông báo của tôi không?
Không theo mặc định. Mã được tạo chỉ từ đặc tả API không bao gồm các giá trị tham số thực hoặc ủy quyền. Để nhận một đoạn mã với mã thông báo và các giá trị thực tế của bạn, hãy gửi yêu cầu trước, sau đó đọc mã từ tab Yêu cầu Thực tế. Hãy coi bất kỳ mã thông báo nào trong đoạn mã đó là bí mật.
Apidog có thể tạo mã cho những ngôn ngữ và thư viện nào?
Một bộ rộng lớn. Shell (cURL, Httpie, wget, PowerShell), JavaScript (Fetch, Axios, jQuery, XHR, và nhiều hơn nữa), Python (http.client và Requests), Java (Unirest, OkHttp), Go, PHP, Swift, C, C#, Ruby, Dart, R, và các ngôn ngữ khác. Bạn chọn ngôn ngữ và biến thể cụ thể trong bảng điều khiển trình tạo.
Tại sao tôi không thấy các tùy chọn Tự động tạo cho phần thân yêu cầu?
Các tùy chọn đó yêu cầu Apidog 2.7.0 trở lên. Cập nhật ứng dụng và chúng sẽ xuất hiện trong tab Chạy khi bạn xây dựng phần thân JSON hoặc XML. Khi có sẵn, menu thả xuống Tự động tạo sẽ cung cấp Ví dụ và Tạo mỗi lần, với các tùy chọn phụ ưu tiên về cách tạo giá trị.
Tính năng tạo mã client có phải là tính năng trả phí không?
Tài liệu Apidog không phân định rõ ràng giữa miễn phí-trả phí hoặc đám mây-tự lưu trữ cho việc tạo mã client. Yêu cầu phiên bản duy nhất được đề cập là các tùy chọn phần thân yêu cầu Tự động tạo cần phiên bản 2.7.0 trở lên. Bạn có thể tải xuống Apidog và thử trình tạo mà không cần gói trả phí.
Làm thế nào để tôi đảm bảo lệnh gọi được tạo thực sự hoạt động?
Tạo đoạn mã, sau đó xác minh endpoint bằng một bài kiểm tra đã lưu. Hướng dẫn của chúng tôi về cách viết kịch bản kiểm tra với Apidog chỉ ra cách xây dựng một kịch bản, và CLI có thể chạy nó trong CI để một hợp đồng bị hỏng sẽ làm thất bại bản dựng trước khi bạn tạo lại client từ đó.
Tóm tắt
Việc tạo mã client trong Apidog biến một đặc tả endpoint thành một yêu cầu sẵn sàng dán bằng bất kỳ ngôn ngữ nào bạn đang làm việc, và tab Yêu cầu Thực tế là bí quyết để đưa các giá trị thực và xác thực vào đoạn mã đó thay vì một mẫu trống. Giữ cho đặc tả có thẩm quyền, tạo lại khi nó thay đổi và để một bài kiểm tra đã lưu xác nhận rằng lệnh gọi vẫn hoạt động. Tải xuống Apidog để thực hiện theo, định nghĩa endpoint GET /orders của bạn và sao chép một lệnh gọi client hoạt động chỉ trong vài cú nhấp chuột.