Mô-đun API của Apidog cho phép bạn xây dựng cùng một hợp đồng API theo hai cách: dùng giao diện trực quan hoặc chỉnh sửa đặc tả OpenAPI/Swagger trực tiếp như mã nguồn. Cả hai đều tạo ra OpenAPI hợp lệ; khác biệt nằm ở quy trình làm việc hằng ngày của nhóm: bạn muốn thiết kế bằng form có kiểm soát, hay quản lý file YAML/JSON trong Git.
Bài viết này đi thẳng vào cách chọn giữa Thiết kế-trước (Design-first) và Đặc tả-trước (Spec-first) trong Apidog: mỗi chế độ hoạt động thế nào, Git được xử lý ra sao, và nhóm nào nên dùng chế độ nào. Bạn có thể chuyển đổi giữa hai chế độ bằng một nút gạt ở góc dưới bên trái của mô-đun API, nên lựa chọn này không cố định. Tuy vậy, chọn đúng chế độ mặc định sẽ giúp giảm ma sát khi thiết kế, review và bảo trì API.
Hai cách tiếp cận hợp đồng API
Cả hai chế độ đều đi theo cùng một nguyên tắc:
Định nghĩa hợp đồng API trước khi viết phần triển khai.
Hợp đồng API là nguồn chân lý. Từ đó bạn có thể sinh tài liệu, mock API, viết test, hoặc đối chiếu thay đổi giữa các phiên bản.
Thiết kế-trước là gì?
Thiết kế-trước (Design-first) nghĩa là bạn tạo hợp đồng API bằng giao diện có cấu trúc:
- Chọn HTTP method.
- Khai báo path.
- Thêm query/path/header parameters.
- Định nghĩa request body.
- Định nghĩa response schema.
- Gắn ví dụ request/response.
Apidog đảm bảo đầu ra là OpenAPI hợp lệ vì bạn thao tác qua form, dropdown và trình chỉnh sửa schema.
Đặc tả-trước là gì?
Đặc tả-trước (Spec-first) nghĩa là bạn viết trực tiếp file đặc tả:
openapi: 3.0.3
info:
title: Orders API
version: 1.0.0
paths:
/orders:
get:
summary: List orders
responses:
'200':
description: OK
Trong chế độ này, file YAML hoặc JSON chính là bề mặt làm việc. Bạn chỉnh sửa nó như mã nguồn, đưa vào Git, review bằng pull request, và đồng bộ với Apidog.
Trong thực tế, các thuật ngữ như “hợp đồng-trước”, “đặc tả-trước” và “thiết kế-trước” thường bị dùng lẫn nhau. Điểm phân biệt quan trọng trong Apidog là:
- Thiết kế-trước: chỉnh sửa qua giao diện trực quan.
- Đặc tả-trước: chỉnh sửa trực tiếp file OpenAPI/Swagger.
Cả hai đều khác với code-first, nơi đặc tả được sinh từ annotation hoặc mã triển khai. Với Apidog, hợp đồng vẫn đi trước mã; chỉ khác ở cách bạn tạo và quản lý hợp đồng đó.
Nếu bạn muốn hiểu thêm về việc coi đặc tả API như một tạo tác được kiểm soát phiên bản, xem thêm bài viết 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ế API trực quan. Bạn tạo endpoint bằng các bước có hướng dẫn:
- Chọn method, ví dụ
GET,POST,PUT,DELETE. - Nhập path, ví dụ
/users/{id}. - Thêm path parameter
id. - Khai báo query/header nếu cần.
- Tạo request body schema.
- Tạo response schema.
- Thêm example để phục vụ mock và tài liệu.
Ví dụ, thay vì tự viết schema YAML, bạn có thể tạo schema User bằng trình chỉnh sửa dạng cây:
{
"id": "string",
"name": "string",
"email": "string"
}
Sau đó dùng lại schema này ở nhiều response khác nhau.
Chế độ này phù hợp khi bạn muốn tránh lỗi cú pháp OpenAPI. Trình chỉnh sửa sẽ kiểm soát cấu trúc nên bạn khó tạo ra đặc tả sai do:
- Thiếu dấu ngoặc.
- Sai kiểu dữ liệu.
- Đặt field không đúng vị trí.
- Quên định nghĩa schema tham chiếu.
Bạn cũng có thể dùng các thành phần tái sử dụng như schema Error, header chung hoặc response mẫu chỉ bằng vài thao tác.
Chế độ Thiết kế-trước cũng hỗ trợ branch trong Apidog. Nhóm có thể thiết kế nhiều phiên bản API song song, sau đó so sánh và đối chiếu thay đổi. Người review sẽ thấy diff có cấu trúc thay vì chỉ đọc YAML thô, điều này hữu ích nếu nhóm có PM, QA hoặc developer chưa quen OpenAPI.
Điểm đánh đổi là bạn làm việc qua một lớp giao diện. Nếu bạn đã quen nghĩ trực tiếp bằng OpenAPI, các form có thể làm chậm luồng chỉnh sửa.
Chế độ Đặc tả-trước của Apidog
Chế độ Đặc tả-trước, hiện đang ở giai đoạn beta, cho phép bạn viết trực tiếp đặc tả OpenAPI hoặc Swagger bằng YAML/JSON trong trình chỉnh sửa kiểu IDE.
Thay vì tạo endpoint qua form, bạn có thể viết trực tiếp:
openapi: 3.0.3
info:
title: Users API
version: 1.0.0
paths:
/users/{id}:
get:
summary: Get user by ID
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: User found
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'404':
description: User not found
components:
schemas:
User:
type: object
required:
- id
- name
properties:
id:
type: string
name:
type: string
email:
type: string
format: email
Trình chỉnh sửa hỗ trợ:
- Tô sáng cú pháp.
- Xác thực nội tuyến.
- Tự động hoàn thành theo OpenAPI/Swagger.
- Phân tích file thành outline ở thanh bên trái.
- Điều hướng nhanh giữa paths và components.
- Chỉ báo đồng bộ với repository Git.
Điểm quan trọng nhất là đồng bộ Git hai chiều. Bạn có thể kết nối repository trên GitHub hoặc GitLab. Azure DevOps hoạt động thông qua Git Connection chung.
Quy trình có thể là:
- Kết nối repository Git với Apidog.
- Chọn file đặc tả OpenAPI/Swagger cần đồng bộ.
- Chỉnh sửa file trong Apidog.
- Commit và push từ Apidog.
- Hoặc chỉnh sửa file trong IDE, push lên Git.
- Pull thay đổi trở lại Apidog.
Như vậy, Apidog không giữ một bản sao riêng biệt của hợp đồng API. File đặc tả trong Git vẫn là nguồn chân lý chung.
Bạn có thể xem hướng dẫn thiết lập trong tài liệu Chế độ Đặc tả-trước.
Chế độ này phù hợp nếu nhóm của bạn đã quen quản lý mọi thứ bằng Git: mã nguồn, cấu hình, hạ tầng và đặc tả API. Thay đổi API có thể được review trong pull request, so sánh từng dòng và kiểm tra trong CI.
Nếu bạn muốn tìm hiểu sâu hơn về cách quản lý đặc tả như mã nguồn, xem thêm bài viết về đặc tả API dưới dạng mã.
So sánh nhanh hai chế độ
Cả hai chế độ đều tạo OpenAPI và có thể dùng cho mock, test, tài liệu và các bước tiếp theo trong vòng đời API. Khác biệt nằm ở cách tạo và kiểm soát phiên bản đặc tả.
| Tiêu chí | Chế độ Thiết kế-trước | Chế độ Đặc tả-trước beta |
|---|---|---|
| Trình chỉnh sửa | Form trực quan và cây schema | Trình chỉnh sửa YAML/JSON kiểu IDE |
| Định dạng đặc tả | OpenAPI được tạo tự động | OpenAPI/Swagger viết thủ công |
| Git workflow | Hỗ trợ branch trong Apidog | Đồng bộ hai chiều với GitHub, GitLab, Azure DevOps qua Git Connection |
| Commit/push | Không phải trọng tâm chính | Có thể commit và push từ Apidog |
| Xác thực | Được kiểm soát bởi các trường nhập liệu | Xác thực cú pháp nội tuyến và autocomplete |
| Điều hướng | Danh sách endpoint và thư mục | Outline tự động từ paths/components |
| Đường cong học tập | Thấp | Cao hơn, cần hiểu OpenAPI |
| Phù hợp nhất cho | Nhóm đa vai trò, cần thao tác nhanh | Nhóm kỹ thuật coi đặc tả là mã |
Khi nào nên dùng Thiết kế-trước?
Chọn Chế độ Thiết kế-trước nếu nhóm của bạn có nhiều vai trò cùng tham gia thiết kế API:
- Backend developer.
- Frontend developer.
- QA.
- Product manager.
- Technical writer.
- Developer mới chưa quen OpenAPI.
Chế độ này hữu ích khi bạn muốn tạo API mới nhanh mà không phải nhớ cú pháp OpenAPI. Ví dụ, khi bắt đầu một endpoint mới:
POST /orders
Bạn có thể thao tác theo checklist:
- Tạo endpoint
POST /orders. - Thêm request body.
- Định nghĩa schema
CreateOrderRequest. - Định nghĩa response
201 Created. - Thêm response lỗi
400 Bad Request. - Tạo example để frontend dùng mock.
- Review thay đổi qua diff trực quan.
Đây là lựa chọn tốt nếu mục tiêu là giảm lỗi định dạng và giúp nhiều người cùng review hợp đồng API.
Khi nào nên dùng Đặc tả-trước?
Chọn Chế độ Đặc tả-trước nếu đặc tả API của bạn đã hoặc nên nằm trong Git cùng với code service.
Chế độ này phù hợp với nhóm backend hoặc platform có workflow như sau:
- Developer sửa file
openapi.yaml. - Tạo pull request.
- Reviewer xem diff OpenAPI.
- CI chạy kiểm tra đặc tả.
- Sau khi merge, Apidog đồng bộ lại file mới.
- Tài liệu, mock và test tiếp tục dựa trên cùng hợp đồng.
Ví dụ repository có thể tổ chức như sau:
services/
user-service/
src/
openapi.yaml
README.md
Hoặc tách đặc tả thành repository riêng:
api-contracts/
users/openapi.yaml
orders/openapi.yaml
billing/openapi.yaml
Nếu nhóm của bạn đã quen review thay đổi bằng pull request, Spec-first sẽ tự nhiên hơn. File YAML/JSON là nguồn chân lý duy nhất, còn Apidog trở thành giao diện để xem, chỉnh sửa, mock, test và tạo tài liệu từ cùng file đó.
Một workflow trung dung
Bạn không nhất thiết phải chọn một chế độ mãi mãi.
Một cách làm thực tế:
- Dùng Thiết kế-trước khi API còn ở giai đoạn phác thảo.
- Tạo nhanh endpoint, schema và example.
- Mời PM, frontend, QA review qua giao diện trực quan.
- Khi API ổn định hơn, chuyển sang Đặc tả-trước.
- Đưa file OpenAPI vào Git.
- Review thay đổi API bằng pull request.
Cách này giúp nhóm tận dụng tốc độ của giao diện trực quan ở giai đoạn đầu, sau đó chuyển sang kiểm soát phiên bản chặt chẽ khi API trưởng thành.
Cách chuyển đổi chế độ trong Apidog
Để chuyển giữa hai chế độ:
- Mở project trong Apidog.
- Vào mô-đun API.
- Nhìn xuống góc dưới bên trái.
- Bấm nút chuyển đổi chế độ.
- Chọn Thiết kế-trước hoặc Đặc tả-trước.
Khi chuyển chế độ, hợp đồng API cơ bản vẫn được giữ nguyên. Bạn chỉ thay đổi bề mặt chỉnh sửa.
Cần lưu ý:
- Endpoint, schema và example vẫn được giữ lại.
- Bạn không phải xây dựng lại API từ đầu.
- Nếu muốn dùng đồng bộ Git trong Chế độ Đặc tả-trước, hãy kết nối repository trước.
- Sau khi kết nối Git, theo dõi chỉ báo đồng bộ để biết thay đổi đã được commit/push hay chưa.
- Vì Chế độ Đặc tả-trước đang beta, hãy thử trên project có thể kiểm chứng trước khi dùng cho hợp đồng production quan trọng.
Checklist chọn chế độ
Dùng checklist này để quyết định nhanh.
Chọn Thiết kế-trước nếu:
- Nhóm không phải ai cũng biết OpenAPI.
- Bạn cần tạo API mới nhanh.
- Bạn muốn review bằng giao diện trực quan.
- Bạn muốn giảm lỗi cú pháp.
- PM, QA hoặc frontend cần tham gia sớm.
Chọn Đặc tả-trước nếu:
- File OpenAPI cần nằm trong Git.
- Nhóm review API qua pull request.
- Bạn muốn so sánh thay đổi từng dòng.
- Bạn đã có CI kiểm tra đặc tả.
- Developer muốn chỉnh sửa bằng YAML/JSON trực tiếp.
- Bạn muốn quản lý hợp đồng API giống mã nguồn.
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. Chế độ Đặc tả-trước của Apidog là một workflow hợp đồng-trước, trong đó hợp đồng là file OpenAPI hoặc Swagger được viết thủ công và đồ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 với GitHub và GitLab. Azure DevOps hoạt động thông qua Git Connection chung, nên bạn cũng có thể đồng bộ file đặc tả với repository đượ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 dữ liệu không?
Có. Cả hai chế độ đọc và ghi cùng một hợp đồng API cơ bản. Endpoint, schema và example vẫn được giữ nguyên khi bạn chuyển chế độ. Bạn chỉ đổi trình chỉnh sửa, không đổi dữ liệu.
Tôi nên bắt đầu từ chế độ nào?
Nếu nhóm chưa có file OpenAPI trong Git, hãy bắt đầu với Thiết kế-trước để tạo cấu trúc API nhanh hơn. Nếu nhóm đã có openapi.yaml hoặc muốn review API bằng pull request, hãy bắt đầu với Đặc tả-trước.
Kết luận
Thiết kế-trước và Đặc tả-trước trong Apidog không phải hai hướng đi cạnh tranh. Chúng là hai cách thao tác trên cùng một hợp đồng API.
- Dùng Thiết kế-trước để thiết kế nhanh, dễ review, ít lỗi cú pháp.
- Dùng Đặc tả-trước khi bạn muốn quản lý OpenAPI như mã nguồn trong Git.
Cách tốt nhất là thử cả hai trên endpoint tiếp theo của bạn. Mở mô-đun API, dùng nút chuyển đổi ở góc dưới bên trái, và xem giao diện nào phù hợp hơn với workflow của nhóm.
Top comments (0)