DEV Community

Cover image for Cách mock API từ CLI
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Cách mock API từ CLI

Bạn cần một API giả để phát triển khi backend chưa sẵn sàng, dịch vụ bên thứ ba bị giới hạn tốc độ, hoặc test không nên phụ thuộc vào máy chủ thật. Vấn đề không phải là có dùng mock hay không, mà là tạo mock theo cách có thể lặp lại: chạy được từ script, CI và tác nhân AI thay vì phải cấu hình lại bằng giao diện mỗi lần.

Dùng thử Apidog ngay hôm nay

Mock được tạo bằng CLI có thể được lưu trong repository, review qua pull request và tái tạo bằng đúng một lệnh. Bài viết này trình bày hai hướng:

  1. Chạy mock cục bộ từ một tệp với Prism, Mockoon CLI hoặc json-server.
  2. Nhập spec và quản lý mock được lưu trữ bằng CLI của Apidog.

Nếu cần so sánh thêm trước khi chọn công cụ, xem các công cụ mock API tốt nhất và các công cụ mock API REST.

Cách chung: chạy máy chủ mock từ một tệp

Nhóm công cụ này biến một tệp spec hoặc dữ liệu thành HTTP endpoint cục bộ. Không cần tài khoản, không cần đăng nhập và không cần tạo dự án.

Chọn công cụ theo đầu vào bạn đang có:

Đầu vào Công cụ phù hợp Điểm chính
Spec OpenAPI Prism Mock theo contract, có xác thực request
Tệp môi trường Mockoon hoặc OpenAPI Mockoon CLI Route được cấu hình phong phú, chạy không cần GUI
Tệp JSON dữ liệu json-server REST API có trạng thái nhanh chóng

Prism: phục vụ spec OpenAPI

Nếu đã có OpenAPI, Prism của Stoplight là cách nhanh để tạo mock dựa trên contract.

npx @stoplight/prism-cli mock ./openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Lệnh này chạy máy chủ tại http://127.0.0.1:4010. Prism đọc:

  • paths để tạo route;
  • example trong response để trả dữ liệu mẫu;
  • schema để sinh dữ liệu hợp lệ khi chưa có example;
  • định nghĩa request để xác thực request đến.

Kiểm tra endpoint:

curl http://127.0.0.1:4010/orders/123
Enter fullscreen mode Exit fullscreen mode

Nếu request không đúng cấu trúc theo spec, Prism trả về mã 422 thay vì bỏ qua lỗi. Đây là lựa chọn phù hợp khi mục tiêu là kiểm tra client có tuân thủ API contract hay không.

Prism là stateless: một request POST không lưu dữ liệu cho request tiếp theo.

Cài đặt toàn cục nếu không muốn dùng npx:

npm install -g @stoplight/prism-cli
Enter fullscreen mode Exit fullscreen mode

Mockoon CLI: chạy tệp dữ liệu mà không cần GUI

Mockoon CLI chạy mock từ tệp môi trường Mockoon hoặc một tệp OpenAPI JSON/YAML. Bạn có thể thiết kế route bằng ứng dụng desktop Mockoon, xuất tệp môi trường, rồi dùng CLI trong CI hoặc trên server.

npx @mockoon/cli start --data ./env.json
Enter fullscreen mode Exit fullscreen mode

Mặc định, Mockoon CLI phục vụ ở cổng 3000. Đổi cổng bằng --port:

npx @mockoon/cli start --data ./env.json --port 8080
Enter fullscreen mode Exit fullscreen mode

Nếu tệp môi trường được tạo bởi phiên bản Mockoon cũ, CLI sẽ di chuyển cấu trúc trong bộ nhớ và không sửa tệp gốc.

Cài đặt toàn cục:

npm install -g @mockoon/cli
Enter fullscreen mode Exit fullscreen mode

Dùng Mockoon CLI khi bạn cần route được tùy chỉnh thủ công nhiều hơn khả năng mà một OpenAPI spec đơn thuần cung cấp, nhưng vẫn muốn chạy mock không cần giao diện. Đây cũng là trường hợp điển hình của một máy chủ mock nhẹ cho API RESTful.

json-server: tạo REST API giả từ JSON

Khi chưa có spec, json-server là lựa chọn nhanh nhất. Chỉ cần tạo tệp JSON chứa dữ liệu.

Ví dụ db.json:

{
  "posts": [
    {
      "id": 1,
      "title": "Bài viết đầu tiên"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Chạy server:

npx json-server db.json
Enter fullscreen mode Exit fullscreen mode

Bạn có ngay endpoint:

http://localhost:3000/posts
Enter fullscreen mode Exit fullscreen mode

json-server hỗ trợ các phương thức REST như:

GET
POST
PUT
PATCH
DELETE
Enter fullscreen mode Exit fullscreen mode

Không giống Prism, POST thực sự thêm bản ghi và ghi lại vào tệp JSON. Vì vậy, đây là lựa chọn phù hợp khi test cần hành vi có trạng thái, chẳng hạn:

  1. Gửi POST /posts.
  2. Gọi GET /posts.
  3. Xác nhận bản ghi vừa tạo xuất hiện trong danh sách.

Cài đặt toàn cục:

npm install -g json-server
Enter fullscreen mode Exit fullscreen mode

Điểm đánh đổi của mock cục bộ

Prism, Mockoon CLI và json-server đều đơn giản: chạy từ một tệp và không cần hạ tầng bổ sung. Tuy nhiên, mock, tài liệu, thiết kế API và test có thể nằm ở các tệp hoặc quy trình riêng biệt. Bạn phải tự đảm bảo chúng luôn đồng bộ.

Nếu cần so khớp request chính xác hoặc phát lại request, MockServer và WireMock cung cấp nhiều khả năng hơn, nhưng yêu cầu môi trường chạy Java.

Cách CLI của Apidog: nhập spec, script các kỳ vọng

Apidog hoạt động khác với Prism hoặc json-server.

CLI apidog không khởi động máy chủ mock cục bộ từ một tệp. Không có lệnh như:

apidog mock ./openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Thay vào đó, Apidog lưu trữ mock. Bạn dùng CLI để:

  1. Nhập spec vào dự án.
  2. Tạo mock thông minh được lưu trữ cho các endpoint.
  3. Tạo, đọc, cập nhật và xóa các kỳ vọng mock tùy chỉnh.

Apidog không phải là mã nguồn mở; đây là sản phẩm thương mại có phiên bản miễn phí. Điểm khác biệt là mock, thiết kế API và test có thể dùng chung một nguồn thông tin trong cùng dự án.

Nếu chỉ cần mock dùng một lần từ một tệp, Prism hoặc json-server thường nhẹ hơn. Nếu mock cần theo kịp API khi spec thay đổi, quy trình của Apidog phù hợp hơn.

Cài đặt và đăng nhập

Cài đặt CLI:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Đăng nhập bằng access token:

apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Xem thêm hướng dẫn cài đặt Apidog CLI để thiết lập token.

Nhập spec để tạo mock thông minh được lưu trữ

Bắt đầu bằng cách nhập OpenAPI vào dự án:

apidog import --project <PROJECT_ID> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

Sau khi nhập, Apidog tạo URL mock cho mỗi endpoint. Bạn không cần khởi động server cục bộ.

Mock thông minh sử dụng kiểu dữ liệu và tên trường từ schema. Ví dụ:

  • Trường email trả về giá trị có định dạng email.
  • Trường createdAt trả về timestamp có định dạng phù hợp.

apidog import cũng hỗ trợ Swagger 2.0, Postman và định dạng Apidog. Điều này giúp bạn đưa định nghĩa API hiện có vào dự án và có mock trực tiếp chỉ bằng một lệnh.

Quản lý phản hồi tùy chỉnh với apidog mock

Mock tự động phù hợp với trường hợp chung. Khi cần phản hồi cụ thể cho từng request, hãy tạo kỳ vọng mock.

Ví dụ use case:

  • Người dùng có ID A nhận 200.
  • Người dùng có ID B nhận 404.
  • Request khớp điều kiện cụ thể trả về payload riêng.

Xem các lệnh hỗ trợ:

apidog mock --help
Enter fullscreen mode Exit fullscreen mode

Liệt kê các kỳ vọng trong dự án:

apidog mock list --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

Lọc theo endpoint:

apidog mock list --project <PROJECT_ID> --http-api-id <ENDPOINT_ID>
Enter fullscreen mode Exit fullscreen mode

Đầu ra là JSON có cấu trúc, vì vậy bạn có thể dùng jq để lọc ID cần dùng cho các bước tiếp theo.

Các thao tác đọc, cập nhật và xóa kỳ vọng:

apidog mock get --project <PROJECT_ID>
apidog mock update --project <PROJECT_ID> --file ./mock.json
apidog mock delete --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

Các lệnh create và update nhận tệp --file mô tả kỳ vọng mock. Hãy xác thực tệp này trước khi ghi.

Xác thực tệp kỳ vọng trước khi tạo hoặc cập nhật

Không nên tự đoán cấu trúc JSON của kỳ vọng. Apidog CLI cung cấp schema cho từng thao tác ghi.

Lấy schema của thao tác tạo mock:

apidog cli-schema get mock-create
Enter fullscreen mode Exit fullscreen mode

Xác thực tệp kỳ vọng:

apidog cli-schema validate mock-create --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

Tạo kỳ vọng sau khi xác thực thành công:

apidog mock create --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

Quy trình nên dùng trong script hoặc CI:

apidog cli-schema validate mock-create --file ./mock.json \
  && apidog mock create --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

Nếu xác thực trả về mã thoát khác 0, pipeline dừng trước khi tệp lỗi được áp dụng vào dự án.

Với thao tác cập nhật, dùng schema key mock-update.

Mỗi lệnh trả về JSON kèm khối agentHints.nextSteps, giúp người dùng hoặc tác nhân AI biết lệnh nên chạy tiếp theo. Xem hướng dẫn hoàn chỉnh về Apidog CLI để tìm hiểu các nhóm lệnh khác.

Tích hợp mock vào CI

Cả hai hướng đều phù hợp với CI vì lệnh CLI có mã thoát và đầu ra văn bản.

Chạy Prism trong job CI

Khởi động Prism nền, chạy test, sau đó dừng process:

# start Prism in the background, then run tests against it
npx @stoplight/prism-cli mock ./openapi.yaml &
PRISM_PID=$!

npm test

kill $PRISM_PID
Enter fullscreen mode Exit fullscreen mode

Test của bạn có thể gọi endpoint tại http://127.0.0.1:4010.

Áp dụng kỳ vọng Apidog trong CI

Với Apidog, không cần khởi động hoặc dừng process cục bộ. Mock đã được lưu trữ, nên CI chỉ cần xác thực và áp dụng kỳ vọng:

# ensure the expectation is well-formed, then apply it
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

Sau đó, test gọi trực tiếp URL mock được lưu trữ.

Lợi ích chính của mock từ CLI là tính tái lập: developer, CI và tác nhân AI đều có thể thiết lập cùng API giả bằng cùng một tập lệnh.

Các lỗi thường gặp

Mong đợi apidog mock khởi động máy chủ

apidog mock không có các lệnh sau:

apidog mock start
apidog mock serve
apidog mock ./file.yaml
Enter fullscreen mode Exit fullscreen mode

Quy trình đúng là:

  1. Dùng apidog import để nhập spec và tạo mock được lưu trữ.
  2. Dùng apidog mock để quản lý các kỳ vọng tùy chỉnh.

Nếu cần chạy một server cục bộ trực tiếp từ tệp, dùng Prism, Mockoon CLI hoặc json-server.

Bỏ qua bước xác thực schema

apidog mock create và apidog mock update nhận tệp qua --file. Tệp sai cấu trúc có thể thất bại hoặc tạo ra cấu hình không mong muốn.

Luôn chạy:

apidog cli-schema get mock-create
apidog cli-schema validate mock-create --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

Hai lệnh bổ sung này giúp tránh mất thời gian gỡ lỗi cấu hình mock.

Prism trả dữ liệu nghèo nàn vì spec quá mỏng

Chất lượng mock Prism phụ thuộc vào OpenAPI spec. Nếu response không có example và schema thiếu chi tiết, dữ liệu trả về cũng sẽ chung chung.

Cải thiện bằng cách thêm example vào response:

responses:
  "200":
    description: Order found
    content:
      application/json:
        schema:
          type: object
          properties:
            id:
              type: string
            status:
              type: string
        example:
          id: "123"
          status: "paid"
Enter fullscreen mode Exit fullscreen mode

Mong đợi trạng thái từ công cụ không trạng thái

Prism và mock hợp đồng của Apidog không duy trì dữ liệu ghi giữa các request.

Nếu cần luồng như sau:

  1. POST /orders
  2. GET /orders/:id
  3. Nhận lại bản ghi vừa tạo

hãy dùng json-server, hoặc cấu hình kỳ vọng Apidog để trả về cấu trúc dữ liệu mong muốn.

Tóm lại

Tạo mock bằng CLI biến thao tác thủ công thành các lệnh có thể script, review và chạy lại trong CI.

  • Dùng Prism khi đã có OpenAPI và cần mock theo contract.
  • Dùng Mockoon CLI khi có tệp môi trường hoặc cần route tùy chỉnh mà không cần GUI.
  • Dùng json-server khi cần REST API có trạng thái từ một tệp JSON.
  • Dùng Apidog khi muốn mock, thiết kế API và test nằm trong cùng một dự án; nhập spec bằng apidog import, sau đó quản lý kỳ vọng bằng apidog mock và cli-schema.

Nếu cần một server dùng một lần từ tệp, các công cụ mã nguồn mở là đủ. Nếu cần mock đồng bộ với thiết kế và test trong dự án, hãy tải xuống Apidog, cài đặt CLI và đưa quy trình mock vào script thay vì thao tác bằng chuột.

Top comments (0)