Cách sinh mã client từ API Spec trong Apidog

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, 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 có thể mất hai mươi phút để tìm lý do máy chủ trả về mã 401.

Dùng thử Apidog ngay hôm nay

Bạn không cần viết tay những đoạn mã trùng lặp đó. Nếu API được thiết kế trong Apidog, nền tảng sẽ đọc đặc tả endpoint và cung cấp đoạn mã yêu cầu sẵn sàng để dán bằng ngôn ngữ bạn đang dùng: cURL để kiểm tra nhanh trong terminal, Python requests cho script, JavaScript fetch hoặc Axios cho frontend.

Bài viết này hướng dẫn cách:

• Tạo mã yêu cầu từ một endpoint thực tế.
• Gửi yêu cầu trước để đưa giá trị thực tế vào đoạn mã.
• Cập nhật mã khi đặc tả API thay đổi.
• Kiểm tra endpoint trong CI bằng Apidog CLI.

Nếu muốn xem thêm các lựa chọn khác, hãy tham khảo bài tổng hợp về các công cụ tạo mã API.

Ý tưởng này dựa trên nguyên tắc đặc tả là nguồn chân lý duy nhất — cũng là nguyên tắc đằng sau OpenAPI Specification. Định nghĩa đúng một lần, rồi tạo mã yêu cầu từ cùng định nghĩa đó.

Trình tạo mã client thực sự làm gì?

Apidog biến định nghĩa endpoint thành đoạn mã yêu cầu theo ngôn ngữ và thư viện HTTP bạn chọn.

Ví dụ, với endpoint GET /orders, khi chọn Python và thư viện Requests, Apidog tạo mã gọi đúng đường dẫn cùng các tiêu đề và tham số được khai báo trong đặc tả.

Đây là trình tạo yêu cầu cho từng endpoint, không phải trình tạo SDK đầy đủ hoặc package client có phiên bản. Bạn có thể dùng nó để tạo:

• Một lệnh cURL để chạy trong terminal.
• Một khối Python requests.
• Một đoạn JavaScript fetch hoặc Axios.
• Mã tương ứng cho nhiều ngôn ngữ và thư viện HTTP khác.

Nếu bạn cần SDK được gõ kiểu đầy đủ, model dữ liệu hoặc tiện ích phân trang tích hợp sẵn, tính năng này không nhằm thay thế các công cụ tạo SDK chuyên dụng.

Quy trình này phù hợp với phát triển API thiết kế trước:

1. Định nghĩa hợp đồng API.
2. Tạo mã yêu cầu trực tiếp từ hợp đồng.
3. Đảm bảo mọi consumer bắt đầu từ cùng một định nghĩa.

Hai cách để mở trình tạo mã

Apidog có hai điểm truy cập vào trình tạo mã client.

Cách 1: Từ tab Tài liệu

Dùng cách này khi bạn đang đọc tài liệu endpoint:

1. Mở tab Tài liệu của API.
2. Chọn endpoint cần dùng.
3. Nhấp Tạo mã Client ở phía bên phải.
4. Chọn ngôn ngữ và thư viện HTTP.

Cách 2: Từ tab Chạy

Dùng cách này khi bạn đã cấu hình hoặc kiểm thử yêu cầu:

1. Mở endpoint trong tab Chạy.
2. Nhấp biểu tượng mã </>.
3. Chọn ngôn ngữ và biến thể thư viện.

Cả hai cách đều mở cùng một bảng điều khiển tạo mã.

Tạo lệnh gọi Python cho GET /orders

Ví dụ dưới đây dùng endpoint GET /orders để liệt kê đơn 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ữ

Mở endpoint trong tab Tài liệu, sau đó nhấp Tạo mã Client.

Apidog hỗ trợ nhiều ngôn ngữ và biến thể:

• 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 và HTTP thô

Trong ví dụ này, chọn Python và Requests. Apidog sẽ tạo đoạn mã tương 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())

Bạn có thể sao chép đoạn mã này vào script và chạy ngay, miễn là endpoint không yêu cầu thông tin xác thực bổ sung.

Bước 2: Hiểu mã được tạo từ đặc tả

Mã tạo trực tiếp từ đặc tả API chỉ chứa thông tin có trong đặc tả:

• URL và HTTP method.
• Header được khai báo.
• Tham số truy vấn hoặc đường dẫn.
• Giá trị ví dụ nếu đặc tả có định nghĩa.
• Cấu trúc body yêu cầu nếu có.

Mã này không tự động chứa mã thông báo xác thực thực tế hoặc giá trị tham số bạn đã nhập khi chạy request.

Ví dụ, đoạn mã từ đặc tả có thể không bao gồm:

Authorization: Bearer <your-token>

Điều này phù hợp nếu endpoint không cần xác thực hoặc bạn muốn tự quản lý token trong mã nguồn. Nhưng với endpoint được bảo vệ như GET /orders, bạn thường cần tạo mã từ một yêu cầu đã gửi thực tế.

Bước 3: Gửi yêu cầu để lấy giá trị thực tế

Để tạo mã có cả tham số và header xác thực thực tế:

1. Mở endpoint trong tab Chạy.
2. Điền tham số yêu cầu.
3. Thêm token xác thực.
4. Nhấp Gửi.
5. Mở tab Yêu cầu Thực tế.
6. Cuộn xuống phần mã client và chọn ngôn ngữ cần dùng.

Nếu làm việc theo hướng thiết kế trước, các tham số từ đặc tả sẽ được điền tự động trong tab Chạy. Nếu đang thiết lập yêu cầu thủ công, hãy nhập chúng trực tiếp.

Sau khi gửi yêu cầu, đoạn Python được tạo có thể trông như sau:

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())

Khác biệt chính là:

Nguồn tạo mã	Nội dung
Từ đặc tả	Cấu trúc endpoint và giá trị ví dụ
Từ Yêu cầu Thực tế	Giá trị tham số và header đã thực sự gửi

Không commit token hoặc khóa API từ đoạn mã được tạo vào Git. Hãy xử lý chúng như bí mật, tương tự khuyến nghị trong tài liệu Stripe về API keys.

Xử lý request body cho POST và PUT

GET /orders không có request body. Tuy nhiên, với POST /orders hoặc PUT /orders/{id}, bạn cần tạo body trước khi sinh mã client.

Trong tab Chạy, Apidog hỗ trợ tạo body JSON hoặc XML từ hai nguồn:

1. Ví dụ request đã được định nghĩa trong đặc tả.
2. Tùy chọn Tự động tạo dựa trên schema.

Menu Tự động tạo có hai chế độ:

• Ví dụ: chọn thủ công một body mẫu đã được định nghĩa.
• Tạo mỗi lần: tạo lại dữ liệu cho mỗi lần sử dụng dựa trên quy tắc mock và schema.

Bạn cũng có thể cấu hình ưu tiên tại 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
• Sử dụng Ví dụ Yêu cầu

Chọn Sử dụng Giá trị Ví dụ trước khi đặc tả đã có dữ liệu ví dụ chất lượng. Chọn Sử dụng Giá trị Mock khi cần dữ liệu mẫu hợp lệ cho từng trường.

Các tùy chọn Tự động tạo cho request body yêu cầu Apidog 2.7.0 trở lên. Nếu không thấy chúng, hãy cập nhật ứng dụng.

Một schema có mô tả tốt, kiểu dữ liệu rõ ràng và ví dụ phù hợp sẽ giúp tạo body chính xác hơn. Bạn có thể cải thiện chất lượng đặc tả bằng cách tự động tạo tài liệu API từ OpenAPI.

Khi cần giá trị thay đổi theo từng yêu cầu, chẳng hạn timestamp hoặc ID ngẫu nhiên:

1. Nhấp biểu tượng đũa thần cạnh trường tham số.
2. Hoặc dùng Chèn Giá trị Động trong body JSON/XML.
3. Gửi yêu cầu.
4. Lấy mã hoàn chỉnh từ tab Yêu cầu Thực tế.

Khi nào dùng đoạn mã yêu cầu thay vì mã trong mô hình nghiệp vụ?

Chọn lượng mã cần sao chép dựa trên nơi đoạn mã sẽ được sử dụng.

Dùng đoạn mã đơn lẻ cho tác vụ một lần

Chọn cURL, fetch đơn giản hoặc requests.get khi bạn cần:

• Gỡ lỗi endpoint trả về 403.
• Chia sẻ request có thể tái tạo trong ticket.
• Kiểm tra nhanh từ terminal.
• Thêm ví dụ vào tài liệu nội bộ.
• Xác minh nhanh header, query string hoặc body.

Ví dụ cURL phù hợp để tái hiện một lỗi ngay lập tức:

curl --request GET \
  --url 'https://api.example.com/orders?status=shipped&page=1' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <TOKEN>'

Dùng mã có cấu trúc trong ứng dụng

Khi endpoint được gọi từ logic ứng dụng, hãy đóng gói mã được tạo vào service hoặc module.

Ví dụ với Python:

import os
import requests

API_BASE_URL = "https://api.example.com"
API_TOKEN = os.environ["API_TOKEN"]

def get_orders(status: str, page: int = 1) -> dict:
    response = requests.get(
        f"{API_BASE_URL}/orders",
        headers={
            "Accept": "application/json",
            "Authorization": f"Bearer {API_TOKEN}",
        },
        params={
            "status": status,
            "page": page,
        },
        timeout=10,
    )
    response.raise_for_status()
    return response.json()

Cách này phù hợp hơn khi GET /orders được dùng ở nhiều nơi vì bạn có thể:

• Tập trung xử lý xác thực.
• Thêm timeout và xử lý lỗi.
• Tái sử dụng logic.
• Không lặp token trong từng request.

Nếu nhiều endpoint dùng chung xác thực hoặc tham số, hãy cấu hình chúng tập trung. Hướng dẫn về cách đặt tham số toàn cục trong Apidog cho thấy cách định nghĩa header và biến dùng chung một lần để các request kế thừa cấu hình đó.

Giữ mã được tạo chính xác với quy trình thiết kế trước

Mã được tạo chỉ chính xác khi đặc tả phía sau nó còn chính xác.

Ví dụ, nếu bạn thêm tham số truy vấn region vào GET /orders nhưng vẫn dùng đoạn mã cũ, request có thể thiếu tham số cần thiết mà không có cảnh báo rõ ràng.

Hãy áp dụng quy trình sau:

1. Cập nhật đặc tả endpoint.
2. Kiểm tra endpoint trong tab Chạy.
3. Gửi request với dữ liệu thực tế.
4. Tạo lại đoạn mã client.
5. Cập nhật service hoặc tài liệu đang dùng đoạn mã cũ.
6. Chạy test để xác minh hợp đồng.

Chế độ thiết kế trước của Apidog giúp giữ định nghĩa API làm nguồn chính thức, để mã yêu cầu luôn phản ánh hợp đồng hiện tại.

Với các đoạn JavaScript được tạo, hãy tham khảo tài liệu MDN về Fetch API nếu cần điều chỉnh cú pháp hoặc xử lý response.

Tự động hóa quy trình với Apidog CLI

Tạo mã client là thao tác trong GUI: bạn mở bảng mã và sao chép đoạn mã cần dùng. Không có lệnh CLI riêng chỉ để xuất mã client.

Tuy nhiên, Apidog CLI giúp tự động hóa hai phần quan trọng:

• Giữ đặc tả API được cập nhật.
• Chạy test để xác minh endpoint vẫn hoạt động đúng hợp đồng.

Cài đặt CLI bằng Node.js v16 trở lên:

npm install -g apidog-cli

Xác thực bằng access token:

apidog login --with-token <YOUR_ACCESS_TOKEN>

Chạy kịch bản kiểm tra đã lưu:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

Trong đó:

• -t: ID kịch bản kiểm tra.
• -e: ID môi trường.
• -r: định dạng báo cáo, gồm cli, html hoặc junit.

Tích hợp lệnh này vào CI để mỗi lần push đều xác minh endpoint vẫn đáp ứng đặc tả trước khi đội ngũ tạo lại mã client. Xem thêm hướng dẫn Apidog CLI với GitHub Actions.

CLI không trực tiếp viết mã client, nhưng nó bảo vệ hợp đồng mà mã client dựa vào.

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

Mã được tạo có bao gồm API key và token không?

Không theo mặc định. Mã tạo trực tiếp từ đặc tả không chứa giá trị tham số thực tế hoặc thông tin xác thực đang dùng.

Để lấy đoạn mã có token và tham số thật:

1. Cấu hình request trong tab Chạy.
2. Gửi request.
3. Mở tab Yêu cầu Thực tế.
4. Sao chép mã client từ request đã gửi.

Không đưa token trong đoạn mã đó vào repository công khai hoặc commit trực tiếp vào Git.

Apidog có thể tạo mã cho ngôn ngữ và thư viện nào?

Apidog hỗ trợ nhiều lựa chọn, bao gồm:

• Shell: cURL, Httpie, wget, PowerShell.
• JavaScript: Fetch, Axios, jQuery, XHR và các biến thể khác.
• Python: http.client, 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à thư viện cụ thể trong bảng tạo mã.

Tại sao tôi không thấy tùy chọn Tự động tạo cho request body?

Các tùy chọn này yêu cầu Apidog 2.7.0 trở lên.

Sau khi cập nhật, bạn sẽ thấy chúng trong tab Chạy khi tạo body JSON hoặc XML. Menu Tự động tạo cung cấp các chế độ Ví dụ và Tạo mỗi lần, cùng các tùy chọn ưu tiên cho giá trị được tạo.

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õ giữa miễn phí/trả phí hoặc cloud/tự lưu trữ đối với tính năng tạo mã client.

Yêu cầu phiên bản được nêu rõ là tùy chọn body Tự động tạo cần Apidog 2.7.0 trở lên. Bạn có thể tải xuống Apidog và thử trình tạo mã.

Làm thế nào để đảm bảo lệnh gọi được tạo thực sự hoạt động?

Sau khi tạo mã:

1. Lưu một kịch bản kiểm tra cho endpoint.
2. Chạy kịch bản trong Apidog.
3. Chạy lại bằng CLI trong CI.
4. Chỉ cập nhật mã client sau khi test xác nhận endpoint hoạt động đúng.

Xem hướng dẫn về cách viết kịch bản kiểm tra với Apidog để thiết lập test cho endpoint.

Tóm tắt

Tạo mã client trong Apidog giúp biến đặc tả endpoint thành request sẵn sàng dán bằng ngôn ngữ và thư viện bạn đang dùng.

Quy trình thực tế:

1. Định nghĩa endpoint trong đặc tả.
2. Mở Tạo mã Client để lấy cấu trúc request.
3. Gửi request trong tab Chạy nếu cần token và giá trị thực tế.
4. Sao chép mã từ tab Yêu cầu Thực tế.
5. Không commit secret vào mã nguồn.
6. Tạo lại mã khi đặc tả thay đổi.
7. Dùng test và CLI để xác minh endpoint trong CI.

Tải xuống Apidog, định nghĩa endpoint GET /orders và tạo một lệnh gọi client hoạt động chỉ trong vài cú nhấp chuột.