Câu hỏi về Postman Collections so với OpenAPI Spec xuất hiện mỗi khi một nhóm phát triển vượt quá vài kỹ sư. Bạn mở collection mình đã viết sáu tháng trước và thấy nó mô tả một endpoint hiện có thêm ba trường bắt buộc, hai tham số đã lỗi thời và một định dạng phản hồi không còn khớp với những gì máy chủ thực sự trả về. OpenAPI spec trong Git lại nói một điều khác. Giao diện Swagger UI của bạn lại hiển thị một điều khác nữa. Không ai chắc chắn cái nào đúng.
Sự sai lệch đó không phải là lỗi công cụ. Đó là lỗi quy trình làm việc, và sự phân biệt này rất quan trọng. Postman là một công cụ tuyệt vời để thực thi yêu cầu, viết script và kiểm thử thăm dò. Vấn đề là khi các nhóm coi collection như một hợp đồng API, thay vì chỉ là một thành phần được tạo ra từ hợp đồng đó.
Tại sao các collection lại sai lệch ngay từ đầu
Một Postman collection là một thành phần ưu tiên yêu cầu. Bạn gửi một yêu cầu, quan sát phản hồi và lưu nó lại. Theo thời gian, bạn thêm các script tiền yêu cầu, thay thế biến, xác nhận kiểm thử và cấu trúc thư mục phản ánh cách nhóm của bạn nghĩ về API, chứ không nhất thiết là những gì API chính thức quy định.
Ngược lại, OpenAPI spec của bạn là một thành phần ưu tiên hợp đồng. Nó khai báo các đường dẫn, tham số, schema và loại phản hồi dưới định dạng máy đọc được mà các công cụ có thể xác thực, tạo mock và tạo mã từ đó.
Hai thành phần này trả lời các câu hỏi khác nhau. Collection trả lời "làm thế nào để tôi gọi endpoint này hôm nay?" Spec trả lời "API này được cho là làm gì?" Khi các nhóm duy trì cả hai một cách độc lập, chúng chắc chắn sẽ khác biệt. Một nhà phát triển cập nhật spec khi hợp nhất một pull request. Một người khác cập nhật collection khi họ nhận thấy một bài kiểm thử bị lỗi. Không ai hợp nhất chúng. Trong vòng vài tháng, bạn có hai mô tả không hoàn toàn chính xác về cùng một API, và không có cách đáng tin cậy để biết cái nào mới hơn.
Bằng chứng từ khách hàng về mô hình này rất rõ ràng. Inventis Korea đã báo cáo chính xác vấn đề này: nhóm của họ đã xây dựng một API, tạo OpenAPI spec cho Swagger, nhập collection vào Postman để kiểm thử, và sau đó tốn công sức liên tục để giữ ba đại diện này đồng bộ. Các bài kiểm thử đã bỏ sót các trường hợp biên vì collection không phản ánh đầy đủ schema. Tài liệu bị sai lệch vì spec không phải là đầu vào để tạo kiểm thử. Đây không phải là các trường hợp hiếm gặp; chúng là những kết quả có thể dự đoán được của một quy trình làm việc ưu tiên yêu cầu ở quy mô lớn.
Nguyên nhân gốc rễ: Postman không được thiết kế để trở thành một kho lưu trữ spec
Postman collections có định dạng riêng. Schema Postman collection là một cấu trúc JSON độc quyền mô tả các yêu cầu, script và cấu trúc thư mục. Nó không phải là OpenAPI. Postman có thể nhập và xuất OpenAPI, nhưng việc chuyển đổi sẽ bị mất mát ở cả hai chiều: OpenAPI sang collection bỏ qua các chi tiết schema không thể biểu thị dưới dạng yêu cầu; collection sang OpenAPI bỏ qua các script và dữ liệu không thể biểu thị dưới dạng trường spec.
Đây không phải là một lời chỉ trích Postman. Đây là mô tả về mục đích thực sự của công cụ. Postman là một trình chạy yêu cầu với các tính năng cộng tác được xây dựng xung quanh mô hình tập trung vào yêu cầu. Việc sử dụng nó làm mô tả API chính thức của bạn đòi hỏi bạn phải áp đặt cấu trúc mà định dạng này không được thiết kế để mang.
So sánh hai cách biểu diễn cho một endpoint duy nhất:
| Thuộc tính | Postman collection | OpenAPI spec |
|---|---|---|
| Tham số yêu cầu | Lưu dưới dạng cặp khóa-giá trị với mô tả tùy chọn | Được định kiểu, xác thực, với các trường required và schema |
| Định dạng phản hồi | Được ghi lại dưới dạng ví dụ đã lưu (tùy chọn) | Được định nghĩa là JSON Schema với việc tái sử dụng $ref trên các đường dẫn |
| Phản hồi lỗi | Thêm thủ công cho mỗi yêu cầu | Liệt kê trong responses với components/schemas được chia sẻ |
| Tái sử dụng schema | Không có; sao chép-dán giữa các yêu cầu | $ref đến components/schemas được thực thi bởi các trình xác thực |
| Hợp đồng máy đọc được | Không | Có; công cụ có thể tạo máy chủ, client, mock |
| Thân thiện với Git diff | JSON với các ID không rõ ràng; khó xem xét có ý nghĩa | YAML; các diff cấp dòng có ý nghĩa |
| Kiểm tra cú pháp và xác thực | Không ở định dạng gốc | Spectral, Redocly CLI và các công cụ khác |
Bảng cho thấy tại sao sự sai lệch xảy ra: collection không thể thể hiện đầy đủ hợp đồng, vì vậy hợp đồng tồn tại ở nơi khác, và hai cái mất đồng bộ ngay khi ai đó chỉnh sửa một cái mà không chỉnh sửa cái còn lại.
Ý nghĩa thực sự của "spec-first" đối với một nhóm Postman
Spec-first không có nghĩa là "thiết kế mọi thứ trong YAML trước khi viết bất kỳ đoạn mã nào". Đối với hầu hết các nhóm chuyển từ quy trình làm việc tập trung vào collection, nó có nghĩa là đảo ngược sự phụ thuộc. Phương pháp spec-first đặt tài liệu OpenAPI vào Git làm mô tả có thẩm quyền về API. Mọi thành phần khác, bao gồm collection bạn sử dụng để kiểm thử, đều được tạo ra từ tài liệu đó, chứ không phải ngược lại.
Trong thực tế, quy trình làm việc trông như thế này:
- Spec được commit vào Git và được xem xét như một phần của quy trình PR.
- Các bài kiểm thử, mock và tài liệu được tạo ra từ spec.
- Khi API thay đổi, spec thay đổi trước tiên. Các thành phần phụ thuộc (downstream artifacts) sẽ tự động cập nhật hoặc thông qua các công cụ.
- Collection mà nhóm của bạn sử dụng để kiểm thử thăm dò được tạo ra từ spec, vì vậy nó luôn phản ánh hợp đồng hiện tại.
Collection vẫn còn đó. Các script, kiểm thử dựa trên dữ liệu và biến môi trường của bạn vẫn còn đó. Sự khác biệt là collection phụ thuộc vào spec (downstream of the spec), chứ không phải ngược lại (upstream of it). Khi một trường mới xuất hiện trong spec, nó sẽ xuất hiện trong collection được tạo ra. Khi một trường bị xóa khỏi spec, bài kiểm thử sẽ thất bại vì yêu cầu được tạo ra không còn bao gồm nó. Sự sai lệch trở thành lỗi CI, chứ không phải là một phát hiện sau sáu tháng.
Cách tạo collection từ spec của bạn
Có một số cách để tạo một collection tương thích với Postman từ OpenAPI spec. Dưới đây là một cách hoạt động với Redocly CLI:
# Install Redocly CLI
npm install -g @redocly/cli
# Validate the spec first
redocly lint openapi/petstore.yaml
# Bundle the spec (resolve $ref chains)
redocly bundle openapi/petstore.yaml -o dist/petstore-bundled.yaml
# Convert to Postman collection v2.1 using the openapi-to-postmanv2 library
npm install -g openapi-to-postmanv2
openapi2postmanv2 \
--spec dist/petstore-bundled.yaml \
--output dist/petstore-collection.json \
--prettyPrint
Đầu ra là một JSON Postman collection tiêu chuẩn. Bạn nhập nó vào Postman hoặc sử dụng nó làm collection cơ sở trong Newman hoặc Postman CLI. Các script tiền yêu cầu và biến môi trường của bạn vẫn là các tệp riêng biệt mà bạn duy trì độc lập; chúng không bị ghi đè khi bạn tạo lại collection từ một spec đã cập nhật.
Bạn có thể tích hợp điều này vào CI để collection luôn được tạo lại từ spec trước khi chạy các bài kiểm thử:
# .github/workflows/api-tests.yml
name: API contract tests
on:
push:
paths:
- "openapi/**"
- "src/**"
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install dependencies
run: |
npm install -g @redocly/cli openapi-to-postmanv2 newman
- name: Validate OpenAPI spec
run: redocly lint openapi/petstore.yaml
- name: Generate collection from spec
run: |
redocly bundle openapi/petstore.yaml -o dist/petstore-bundled.yaml
openapi2postmanv2 \
--spec dist/petstore-bundled.yaml \
--output dist/petstore-collection.json
- name: Run tests against generated collection
run: |
newman run dist/petstore-collection.json \
--environment config/env-staging.json \
--reporters cli,junit \
--reporter-junit-export results/test-results.xml
- name: Upload test results
uses: actions/upload-artifact@v4
with:
name: test-results
path: results/
Với mô hình này, spec là đầu vào cho mỗi lần chạy kiểm thử. Một thay đổi trong spec làm hỏng một bài kiểm thử sẽ được phát hiện trong cùng PR đã thay đổi spec đó.
Apidog phù hợp với quy trình làm việc này ở đâu
Giá trị của Apidog không phải là nó thay thế Postman như một trình chạy yêu cầu. Mà là nó kết nối OpenAPI spec với mọi thành phần khác mà nhóm của bạn làm việc cùng, mà không cần bước chuyển đổi thủ công. Spec trong Git vẫn là nguồn sự thật; Apidog là lớp cộng tác và thực thi trên đó.
Chế độ Spec-First của Apidog (hiện đang trong giai đoạn beta) cho phép bạn đồng bộ hóa OpenAPI spec từ một kho lưu trữ Git trực tiếp vào không gian làm việc của Apidog. Từ spec đã đồng bộ đó, bạn sẽ có các mock tự động tạo, tài liệu tương tác và các kịch bản kiểm thử, tất cả đều được cập nhật tự động khi spec thay đổi trong Git. Bạn không cần duy trì một collection riêng biệt bên cạnh spec; spec sẽ điều khiển những gì Apidog hiển thị và thực thi.
Điều này quan trọng đối với các nhóm gặp phải tình trạng mà STC Group và Diễn đàn Kinh tế Thế giới đã mô tả: duy trì Postman để kiểm thử, một công cụ tài liệu riêng biệt để hiển thị spec, và một máy chủ mock cho phát triển frontend, ba hệ thống đều cần phản ánh cùng một hợp đồng API. Khi spec thay đổi, bạn cập nhật nó ở một nơi và cả ba bề mặt đều cập nhật. Đáng để kiểm tra trong bản dùng thử xem quyền truy cập không gian làm việc và độ chi tiết của SSO của Apidog có đáp ứng các yêu cầu kiểm soát truy cập cụ thể của bạn hay không, đặc biệt đối với các nhóm lớn như triển khai của DHL được mô tả (hơn 100 người dùng). Đó là những câu hỏi đánh giá có ý nghĩa cho một bằng chứng khái niệm.
Đối với lộ trình di chuyển, bạn có thể chuyển đổi các Postman collection hiện có của mình sang Apidog làm điểm khởi đầu, sau đó biến spec thành tài liệu chính thức từ đó về sau. Bước nhập tự động được trình bày chi tiết trong hướng dẫn được liên kết.
Coi spec như mã trong quy trình làm việc Git của bạn
Cách tiếp cận api-spec-as-code có nghĩa là tài liệu OpenAPI được xử lý giống như mã ứng dụng: pull request, xem xét mã, kiểm tra cú pháp trong CI và thẻ phiên bản tại các ranh giới phát hành. Hầu hết các nhóm đều thấy rằng họ đã có cơ sở hạ tầng cho việc này; bước còn thiếu là áp dụng nó cho tệp spec.
Một vài thực tiễn hữu ích:
- Lưu trữ spec trong cùng một kho lưu trữ với dịch vụ mà nó mô tả, không phải trong một kho lưu trữ "docs" riêng biệt. Điều này đảm bảo các thay đổi spec xảy ra trong cùng PR với các thay đổi mã.
- Thêm bước kiểm tra cú pháp Spectral vào pipeline CI của bạn. Spectral xác thực spec dựa trên đặc tả OpenAPI và bất kỳ quy tắc tùy chỉnh nào mà nhóm của bạn định nghĩa. Các tham chiếu schema bị hỏng, mô tả bị thiếu và đặt tên không nhất quán sẽ trở thành lỗi CI, chứ không phải là nhận xét đánh giá.
- Sử dụng phát triển spec dựa trên nhánh cho các thay đổi lớn, giống như cách bạn phân nhánh mã ứng dụng. Các không gian làm việc của Apidog hỗ trợ phân nhánh trên spec, vì vậy các nhóm khác nhau có thể làm việc trên một nhánh ổn định trong khi một thay đổi lớn đang được xem xét.
- Ghim các phiên bản spec trong các kho lưu trữ tiêu dùng phụ thuộc (downstream consumer repositories). Khi dịch vụ B phụ thuộc vào spec của dịch vụ A cho các kiểm thử hợp đồng, nó nên tham chiếu một thẻ phiên bản cụ thể, chứ không phải HEAD của main.
Cách tiếp cận này được trình bày chi tiết trong hướng dẫn quy trình làm việc API gốc Git nếu bạn muốn thiết lập từng bước cho một dự án mới.
Câu hỏi thường gặp
Tôi có phải ngừng sử dụng Postman hoàn toàn không?
Không. Thay đổi về phương pháp luận là về hướng phụ thuộc, chứ không phải thay thế công cụ. Bạn có thể tiếp tục sử dụng Postman để kiểm thử thăm dò và viết script. Sự khác biệt là collection của bạn được tạo ra từ spec trước mỗi lần chạy kiểm thử, thay vì được duy trì như một thành phần riêng biệt. Nếu nhóm của bạn thích giao diện người dùng của Postman cho công việc thăm dò, sở thích đó vẫn tương thích với quy trình làm việc ưu tiên spec.
Điều gì xảy ra với các script và biến môi trường Postman hiện có của chúng tôi?
Các script tiền yêu cầu, script kiểm thử và định nghĩa biến môi trường của bạn không phải là một phần của collection được tạo ra. Chúng là các tệp riêng biệt mà bạn duy trì độc lập. Khi bạn tạo lại collection từ một spec đã cập nhật, các script sẽ không bị ghi đè. Bạn giữ lớp hành vi (script) trong khi lớp cấu trúc (định nghĩa yêu cầu) luôn được tạo ra từ spec.
Làm thế nào để tôi xử lý các endpoint chưa có trong spec?
Trong quy trình làm việc ưu tiên spec, một endpoint không có trong spec thì chưa sẵn sàng để kiểm thử. Điều đó nghe có vẻ nghiêm ngặt, nhưng đó là mấu chốt: cổng spec đảm bảo rằng các endpoint mới được mô tả chính thức trước khi viết các bài kiểm thử cho chúng. Đối với phát triển thăm dò, bạn có thể làm việc với một stub cục bộ và thêm mục spec như một phần của PR giới thiệu endpoint. Tham khảo hướng dẫn các công cụ xác thực OpenAPI tốt nhất để tìm các công cụ giúp bước chỉnh sửa ưu tiên spec nhanh hơn.
Chế độ Spec-First của Apidog đã có sẵn chưa?
Chế độ Spec-First của Apidog hiện đang trong giai đoạn beta. Bạn có thể truy cập nó thông qua Apidog và đánh giá xem quy trình làm việc đồng bộ Git, hỗ trợ nhánh và các mock tự động tạo có đáp ứng yêu cầu của nhóm bạn hay không. Giống như bất kỳ tính năng beta nào, đáng để kiểm thử với cấu trúc spec cụ thể của bạn trước khi cam kết sử dụng nó như một quy trình làm việc sản xuất.
Sự khác biệt giữa điều này và việc nhập spec của tôi vào Postman là gì?
Postman có thể nhập một OpenAPI spec và tạo một collection từ đó. Đó là một chuyển đổi một lần. Collection sau đó được duy trì độc lập với spec, vì vậy sự sai lệch sẽ tiếp tục ngay lập tức. Một quy trình làm việc ưu tiên spec sẽ tạo lại collection từ spec trong mỗi lần chạy CI (hoặc đồng bộ hóa), vì vậy collection không bao giờ lỗi thời quá một bản build so với spec.
Kết luận
Vấn đề sai lệch mà nhóm của bạn đang gặp phải không phải là một lỗi trong Postman. Đó là kết quả có thể dự đoán được của việc duy trì hai mô tả API chồng chéo một phần mà không có sự phụ thuộc rõ ràng giữa chúng. Giải pháp là thiết lập OpenAPI spec trong Git làm nguồn có thẩm quyền, và coi Postman collection như một thành phần được tạo ra phụ thuộc vào spec đó.
Sự đảo ngược đó thay đổi những gì bị hỏng và khi nào. Các thay đổi spec làm hỏng kiểm thử sẽ bị phát hiện trong PR đã tạo ra chúng. Tài liệu, mock và kịch bản kiểm thử vẫn đồng bộ vì tất cả đều đọc từ cùng một nguồn. Gánh nặng bảo trì để giữ hai hệ thống đồng bộ biến mất vì chỉ có một hệ thống.
Tải xuống Apidog và mở không gian làm việc Chế độ Spec-First với OpenAPI spec hiện có của bạn. Nếu bạn bắt đầu từ một collection thay vì một spec, bạn có thể nhập collection đó làm điểm khởi đầu OpenAPI và sau đó tiếp tục làm việc theo hướng spec từ đó. Quy trình làm việc đồng bộ Git trở nên rõ ràng hơn khi bạn thấy nó chạy trên API của chính mình, thay vì một ví dụ phức tạp.