Mô-đun API của Apidog cung cấp cho bạn hai cách để xây dựng cùng một thứ: một hợp đồng API. Một cách sử dụng biểu mẫu trực quan. Cách còn lại sử dụng trình chỉnh sửa mã thô được kết nối với Git. Cả hai đều tạo ra OpenAPI hợp lệ. Sự khác biệt nằm ở cách nhóm của bạn làm việc hàng ngày, và cách nào phù hợp ít phụ thuộc vào công cụ mà phụ thuộc nhiều hơn vào thói quen của bạn.
Hướng dẫn này sẽ đi sâu vào quyết định thiết kế-trước (design-first) so với đặc tả-trước (spec-first) trong Apidog: mỗi chế độ là gì, cách chúng xử lý Git và nhóm nào có xu hướng chọn chế độ nào. Bạn chuyển đổi giữa chúng từ một nút gạt duy nhất ở phía dưới bên trái của mô-đun API, vì vậy lựa chọn này không cố định. Nhưng việc chọn chế độ mặc định phù hợp sẽ giúp giảm ma sát.
Hai triết lý
Trước khi nói về các chế độ, hãy nói về tư duy. Cả hai cách tiếp cận đều chia sẻ một quy tắc: bạn định nghĩa hợp đồng API trước khi viết phần triển khai. Hợp đồng là nguồn chân lý. Mã, kiểm thử, mô phỏng và tài liệu đều bắt nguồn từ nó.
Thiết kế-trước (Design-first) có nghĩa là bạn định hình hợp đồng đó thông qua một giao diện có cấu trúc. Bạn thêm các điểm cuối (endpoints), tham số và lược đồ thông qua các biểu mẫu và danh sách thả xuống. Công cụ đảm bảo đầu ra hợp lệ vì bạn chỉ có thể nhập các giá trị hợp lệ.
Đặc tả-trước (Spec-first, thường được gọi là hợp đồng-trước) có nghĩa là bạn viết hợp đồng trực tiếp dưới dạng một tệp đặc tả: OpenAPI bằng YAML hoặc JSON. Đặc tả là bề mặt làm việc của bạn. Bạn chỉnh sửa nó như mã nguồn.
Các thuật ngữ này chồng chéo trong thực tế. "Hợp đồng-trước" và "đặc tả-trước" là những từ gần nghĩa, và nhiều nhóm sử dụng "thiết kế-trước" một cách lỏng lẻo để chỉ bất kỳ cách tiếp cận nào mà hợp đồng có trước mã. Sự phân biệt hữu ích ở đây là cụ thể: trong Apidog, một chế độ cung cấp cho bạn các biểu mẫu, chế độ kia cung cấp cho bạn một trình soạn thảo văn bản. Đó là ranh giới quan trọng khi bạn lựa chọn.
Điều đáng lưu ý là phải tách biệt cả hai khỏi quá trình phát triển API thiết kế-trước so với mã-trước (code-first). Mã-trước tạo ra đặc tả từ các chú thích trong phần triển khai của bạn, do đó mã là yếu tố dẫn đầu. Cả hai chế độ của Apidog đều giữ hợp đồng ở phía trước mã. Chúng chỉ khác nhau về cách bạn tạo ra nó. Để có cái nhìn tổng quan hơn về việc coi đặc tả của bạn như một tạo tác được kiểm soát phiên bản, hãy xem tổng quan của chúng tôi về quy trình làm việc API Git-native.
Chế độ Thiết kế-trước của Apidog
Chế độ Thiết kế-trước là trình thiết kế trực quan. Bạn xây dựng các điểm cuối thông qua một giao diện hướng dẫn: chọn một phương thức, đặt tên đường dẫn, thêm tham số truy vấn và đường dẫn, định nghĩa lược đồ yêu cầu và phản hồi thông qua trình chỉnh sửa dạng cây, và đính kèm các ví dụ. Apidog sẽ hiển thị OpenAPI cơ bản cho bạn ở chế độ nền.
Chế độ này là mặc định cho hầu hết các nhóm, và có lý do chính đáng. Bạn không cần phải nhớ cú pháp OpenAPI. Trình chỉnh sửa lược đồ sẽ thực thi cấu trúc, vì vậy bạn không thể phát hành một đặc tả với một dấu ngoặc sai vị trí hoặc một kiểu dữ liệu không hợp lệ. Các thành phần có thể tái sử dụng, như lược đồ Error chung hoặc tiêu đề phổ biến, chỉ cách bạn vài cú nhấp chuột.
Chế độ Thiết kế-trước cũng hỗ trợ các nhánh (branches), vì vậy các nhóm có thể làm việc trên các phiên bản thiết kế API riêng biệt song song và đối chiếu chúng sau này. Người đánh giá sẽ thấy một bản so sánh có cấu trúc thay vì văn bản thô, điều này giúp việc đọc các thay đổi hợp đồng dễ dàng hơn đối với những người không quen thuộc với YAML.
Sự đánh đổi: bạn đang làm việc thông qua một lớp trừu tượng. Nếu bạn đã quen tư duy bằng OpenAPI, các biểu mẫu có thể tạo cảm giác như thêm những cú nhấp chuột không cần thiết giữa bạn và đặc tả mà bạn đang hình dung.
Chế độ Đặc tả-trước của Apidog
Chế độ Đặc tả-trước, hiện đang trong giai đoạn beta, đảo ngược điều đó. Thay vì các biểu mẫu, bạn có một trình chỉnh sửa mã kiểu IDE và bạn viết đặc tả OpenAPI hoặc Swagger trực tiếp bằng YAML hoặc JSON. Nó được xây dựng cho các nhóm muốn định nghĩa API của họ nằm trong Git giống như bất kỳ tệp nguồn nào khác.
Trình chỉnh sửa hoạt động giống như trình chỉnh sửa trong IDE của bạn: tô sáng cú pháp, xác thực nội tuyến và tự động hoàn thành được điều chỉnh cho lược đồ OpenAPI và Swagger. Khi bạn gõ, một thanh bên trái sẽ tự động phân tích đặc tả của bạn thành một dàn ý các đường dẫn và thành phần, giúp bạn điều hướng một tệp lớn mà không cần cuộn. Một chỉ báo đồng bộ hóa cho biết liệu các chỉnh sửa cục bộ của bạn có đồng bộ với kho lưu trữ được kết nối hay không.
Điểm nổi bật là tính năng đồng bộ Git hai chiều. Bạn kết nối một kho lưu trữ trên GitHub hoặc GitLab (Azure DevOps hoạt động thông qua một kết nối Git chung), và Apidog sẽ đồng bộ tệp đặc tả của bạn theo cả hai hướng. Chỉnh sửa trong Apidog, sau đó cam kết (commit) và đẩy (push) trực tiếp từ ứng dụng. Hoặc chỉnh sửa đặc tả trong trình chỉnh sửa mã của bạn, đẩy từ đó, và kéo các thay đổi trở lại Apidog. Tệp đặc tả là nguồn chân lý chung, và cả hai bề mặt đều được căn chỉnh. Bạn có thể đọc toàn bộ thiết lập trong tài liệu Chế độ Đặc tả-trước.
Chế độ này xử lý hợp đồng API của bạn theo cách bạn xử lý bất kỳ tạo tác mã nào khác: được xem xét trong các pull request, được kiểm soát phiên bản cùng với các dịch vụ triển khai nó, và được so sánh từng dòng. Nếu đó là cách nhóm của bạn đã quản lý hạ tầng và cấu hình, hãy xem bài viết sâu hơn của chúng tôi về đặc tả API dưới dạng mã để hiểu rõ lý do đằng sau.
So sánh song song
Cả hai chế độ đều tạo ra OpenAPI giống nhau và hỗ trợ mô phỏng (mocking), kiểm thử và tài liệu ở các bước tiếp theo. Chúng khác nhau ở cách bạn tạo và kiểm soát phiên bản đặc tả.
| Chế độ Thiết kế-trước | Chế độ Đặc tả-trước (beta) | |
|---|---|---|
| Trình chỉnh sửa | Biểu mẫu trực quan và cây lược đồ | Trình chỉnh sửa mã YAML/JSON kiểu IDE |
| Định dạng đặc tả | OpenAPI (được tạo tự động) | OpenAPI / Swagger, viết thủ công |
| Quy trình làm việc Git | Hỗ trợ nhánh trong Apidog | Đồng bộ hai chiều với GitHub, GitLab, Azure DevOps (Kết nối Git); cam kết và đẩy từ ứng dụng |
| Xác thực | Được thực thi bởi các trường nhập liệu | Xác thực cú pháp nội tuyến và tự động hoàn thành |
| Điều hướng | Danh sách điểm cuối và thư mục | Dàn ý được tự động phân tích cú pháp ở thanh bên trái |
| Đường cong học tập | Thấp; không cần kiến thức OpenAPI | Cao hơn; yêu cầu thông thạo OpenAPI |
| Tốt nhất cho | Các nhóm có kỹ năng đa dạng, làm quen nhanh | Các kỹ sư coi đặc tả là mã |
Nhóm nào nên chọn chế độ nào
Sử dụng Chế độ Thiết kế-trước nếu những người đóng góp của bạn không phải tất cả đều là chuyên gia OpenAPI. Các quản lý sản phẩm, QA và kỹ sư mới có thể thêm hoặc xem xét các điểm cuối mà không cần học cú pháp đặc tả. Đây cũng là con đường nhanh hơn khi bạn bắt đầu một API mới từ đầu và muốn nhanh chóng xây dựng cấu trúc mà không phải lo lắng về định dạng.
Sử dụng Chế độ Đặc tả-trước nếu đặc tả của bạn đã hoặc nên nằm trong một kho lưu trữ Git bên cạnh mã dịch vụ của bạn. Các nhóm backend xem xét thay đổi API trong các pull request, chạy kiểm tra đặc tả trong CI, hoặc muốn có một tệp YAML chuẩn duy nhất trên các công cụ sẽ cảm thấy thoải mái. Đồng bộ hai chiều có nghĩa là Apidog không còn là một bản sao riêng biệt của sự thật mà trở thành một cửa sổ nhìn vào cùng một tệp mà kho lưu trữ của bạn đang giữ.
Một con đường trung dung thực tế: nhiều nhóm thiết kế các điểm cuối mới trong Chế độ Thiết kế-trước để tăng tốc, sau đó chuyển sang Đặc tả-trước khi API trưởng thành và việc xem xét Git trở thành ưu tiên. Các chế độ này không phải là sản phẩm cạnh tranh. Chúng là hai góc nhìn của cùng một hợp đồng.
Cách chuyển đổi chế độ
Việc chuyển đổi chỉ là một nút gạt duy nhất. Mở mô-đun API trong dự án Apidog của bạn và nhìn vào góc dưới bên trái, nơi có nút chuyển đổi chế độ. Nhấp vào đó, và cùng một hợp đồng sẽ được hiển thị ở chế độ khác.
Một vài điều cần lưu ý khi bạn chuyển đổi:
- Đặc tả cơ bản được chia sẻ, vì vậy các điểm cuối, lược đồ và ví dụ của bạn sẽ được giữ nguyên. Bạn đang thay đổi bề mặt chỉnh sửa, chứ không phải xây dựng lại API.
- Để sử dụng tính năng đồng bộ Git của Chế độ Đặc tả-trước, trước tiên hãy kết nối kho lưu trữ GitHub, GitLab hoặc Azure DevOps của bạn. Sau khi kết nối, chỉ báo đồng bộ hóa sẽ cho bạn biết liệu các chỉnh sửa của bạn đã được cam kết và đẩy hay chưa.
- Vì Chế độ Đặc tả-trước đang trong giai đoạn beta, hãy thử nghiệm nó trên một dự án mà bạn có thể xác nhận hành vi đồng bộ hóa trước khi dựa vào nó cho một hợp đồng sản xuất.
Bạn có thể chuyển đổi qua lại khi nhu cầu của mình thay đổi, vì vậy hãy coi lựa chọn này là mặc định chứ không phải là một cam kết.
Câu hỏi thường gặp (FAQ)
Đặc tả-trước có giống hợp đồng-trước không?
Trong thực tế, có. Cả "đặc tả-trước" và "hợp đồng-trước" đều có nghĩa là bạn tạo đặc tả API trước khi triển khai, và cả hai đều coi đặc tả đó là nguồn chân lý. Chế độ Đặc tả-trước của Apidog là một quy trình làm việc hợp đồng-trước, trong đó hợp đồng là một tệp OpenAPI hoặc Swagger được viết thủ công và được đồng bộ với Git.
Chế độ Đặc tả-trước có hoạt động với GitLab và Azure DevOps không?
Có. Chế độ Đặc tả-trước hỗ trợ đồng bộ Git hai chiều trực tiếp với GitHub và GitLab. Azure DevOps hoạt động thông qua một Kết nối Git chung, vì vậy bạn cũng có thể đồng bộ tệp đặc tả của mình với một kho lưu trữ được lưu trữ trên Azure.
Tôi có thể chuyển từ thiết kế-trước sang đặc tả-trước mà không mất công việc không?
Có. Cả hai chế độ đều đọc và ghi cùng một hợp đồng cơ bản, vì vậy các điểm cuối, lược đồ và ví dụ của bạn vẫn nguyên vẹn khi bạn bật nút gạt ở phía dưới bên trái của mô-đun API. Bạn đang thay đổi trình chỉnh sửa, chứ không phải dữ liệu.
Không chắc chế độ nào phù hợp với nhóm của bạn? Mở mô-đun API, thử nút chuyển đổi chế độ ở phía dưới bên trái, và thiết kế điểm cuối tiếp theo của bạn theo cả hai cách. Hợp đồng vẫn giống nhau dù theo cách nào; hãy chọn giao diện phù hợp với cách nhóm của bạn đang làm việc.