Quy trình API Git-Native là gì (và cách xây dựng)?

Mã của bạn nằm trong Git. Pipeline CI, review và lịch sử phát hành cũng nằm trong Git. Vậy đặc tả API của bạn cũng nên nằm trong cùng repo, dưới dạng một tệp OpenAPI có thể commit, diff và review như code.

Dùng thử Apidog ngay hôm nay

Quy trình API bản địa Git giúp bạn quản lý OpenAPI như mã nguồn: chỉnh sửa YAML/JSON, commit thay đổi, tạo pull request, chạy CI và merge theo cùng quy trình với ứng dụng. Không cần database đám mây riêng, không cần export/import thủ công, không có “nguồn chân lý” thứ hai.

💡 Apidog hỗ trợ quy trình này với Chế độ ưu tiên đặc tả (Spec-First Mode). Bạn thiết kế API trong trình chỉnh sửa kiểu IDE, sau đó đồng bộ hai chiều các tệp thô với GitHub hoặc GitLab.

Quy trình làm việc API bản địa Git là gì?

Quy trình làm việc API bản địa Git coi đặc tả API là một phần của mã nguồn. Tệp OpenAPI nằm trong repo cùng service, ví dụ:

.
├── src/
├── tests/
├── openapi/
│   └── orders.yaml
└── package.json

Mỗi thay đổi API trở thành một commit có tác giả, message và diff rõ ràng.

Cách làm này mang lại ba lợi ích thực tế:

• Lịch sử phiên bản rõ ràng: dùng git log, git blame, hoặc diff để biết ai đã sửa endpoint nào và khi nào.
• Review qua pull request: thay đổi đặc tả đi qua cùng quy trình review với code.
• Một nguồn chân lý duy nhất: tệp OpenAPI trên nhánh chính là hợp đồng API để tài liệu, mock, lint, test và codegen cùng sử dụng.

Ví dụ, khi thêm response 404 cho endpoint GET /orders/{orderId}, reviewer có thể thấy chính xác phần thay đổi trong pull request thay vì phải mở một công cụ thiết kế riêng.

Đây cũng là nền tảng của phát triển API ưu tiên đặc tả: đặc tả đi trước, implementation đi sau.

Vấn đề khi đặc tả API bị khóa trên đám mây

Nhiều công cụ thiết kế API lưu đặc tả trong database riêng. Bạn chỉnh sửa qua UI, nhưng “tệp OpenAPI” thực chất không nằm trong repo của bạn.

Điều này thường gây ra các vấn đề sau:

Review bị tách khỏi Git

Code review diễn ra trên GitHub/GitLab, còn review API lại nằm trong một công cụ khác. Reviewer phải chuyển ngữ cảnh, comment bị phân tán, approval dễ lệch nhau.

Diff không rõ ràng

Khi đặc tả nằm trong hệ thống đám mây riêng, pull request không hiển thị diff từng dòng. Bạn có thể đang approve “phiên bản thiết kế mới” mà không biết chính xác schema, response hoặc endpoint nào đã đổi.

Export/import trở thành bước thủ công

Để chạy CI, bạn cần export OpenAPI, commit tệp đã export, rồi hy vọng không ai sửa bản trên cloud trong lúc đó. Kết quả là có hai nguồn chân lý và dễ phát sinh conflict.

Automation bị phức tạp hóa

Các bước như lint OpenAPI, contract test hoặc code generation đều cần một tệp trên đĩa:

npx spectral lint openapi/orders.yaml

Nếu đặc tả bị khóa trên cloud, pipeline phải thêm bước fetch/export trước khi chạy kiểm tra.

Cách tiếp cận Đặc tả API như mã nguồn loại bỏ lớp phức tạp này: tệp là đặc tả, Git là lịch sử, CI xử lý phần còn lại.

Chế độ ưu tiên đặc tả của Apidog hoạt động như thế nào?

Chế độ ưu tiên đặc tả dành cho các nhóm đã quen làm việc với commit, branch và pull request. Bạn chỉnh sửa OpenAPI dưới dạng YAML hoặc JSON thô, còn Apidog đồng bộ hai chiều các tệp đó với repo Git.

1. Chỉnh sửa OpenAPI bằng editor kiểu IDE

Thay vì điền form, bạn viết trực tiếp đặc tả trong trình chỉnh sửa mã. Editor hỗ trợ:

• Tô sáng cú pháp YAML/JSON.
• Xác thực theo schema OpenAPI và Swagger.
• Tự động hoàn thành keyword, type và $ref.

Bạn vẫn kiểm soát chính xác nội dung tệp. Không có field ẩn hoặc metadata chỉ dành cho UI.

2. Làm việc với tệp YAML/JSON thô

Ví dụ một phần đặc tả OpenAPI:

openapi: 3.1.0
info:
  title: Orders API
  version: 1.2.0

paths:
  /orders/{orderId}:
    get:
      summary: Get an order by ID
      operationId: getOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Order found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "404":
          description: Order not found

components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [pending, shipped, delivered]

Đây là tệp sẽ được commit vào repo. Những gì bạn chỉnh sửa là những gì Git ghi nhận.

3. Điều hướng đặc tả bằng outline tự động

Khi bạn gõ, Apidog phân tích tệp và tạo outline ở sidebar. Paths, operations và schemas được hiển thị dạng cây để bạn nhảy nhanh đến phần cần sửa.

Với đặc tả dài hàng trăm hoặc hàng nghìn dòng, bạn không cần cuộn thủ công để tìm endpoint.

4. Đồng bộ Git hai chiều

Chế độ ưu tiên đặc tả kết nối với Git provider và đồng bộ thay đổi theo hai chiều.

Theo nội dung hiện tại, Apidog hỗ trợ:

• GitHub.
• GitLab.
• Azure DevOps thông qua Git Connection.

Luồng làm việc cơ bản:

Pull từ repo → chỉnh sửa trong Apidog → commit → push lên branch

Repo và workspace luôn được giữ đồng bộ.

5. Commit, push và kiểm tra trạng thái đồng bộ

Bạn có thể stage thay đổi, viết commit message và push ngay trong Apidog. Trạng thái đồng bộ cho biết workspace hiện đang khớp với remote hay chưa.

Ví dụ commit message tốt:

Add 404 response for getOrder

Tránh message chung chung như:

Update spec

Sau khi push thành công, trạng thái hiển thị “Đã đồng bộ ngay bây giờ”. Nếu đổi ý trước khi push, bạn có thể loại bỏ chỉnh sửa chưa đẩy và quay lại trạng thái đồng bộ gần nhất.

Xem thêm hướng dẫn đồng bộ hóa đặc tả OpenAPI với GitHub.

Hướng dẫn thiết lập Chế độ ưu tiên đặc tả

Dưới đây là quy trình từ repo đến đặc tả đã đồng bộ. Tài liệu đầy đủ có trong tài liệu Chế độ ưu tiên đặc tả.

Bước 1: Tạo dự án từ repo Git

Trong Apidog, tạo dự án Chế độ ưu tiên đặc tả mới và kết nối Git provider của bạn.

Chọn:

• Repo chứa đặc tả API.
• Branch cần theo dõi, thường là main.
• Tệp OpenAPI hiện có, nếu repo đã có sẵn.

Apidog sẽ kéo các tệp đặc tả vào editor.

Bước 2: Chỉnh sửa đặc tả OpenAPI

Mở tệp YAML hoặc JSON trong editor. Bạn có thể:

• Thêm endpoint mới.
• Sửa request/response.
• Cập nhật schema.
• Thêm mã lỗi như 400, 401, 404, 500.

Ví dụ thêm response 404:

responses:
  "200":
    description: Order found
  "404":
    description: Order not found

Trong khi chỉnh sửa, editor sẽ hỗ trợ syntax highlight, validation và autocomplete. Outline bên trái cũng cập nhật theo nội dung tệp.

Bước 3: Kiểm tra các tệp đã thay đổi

Apidog hiển thị các tệp đã:

• Sửa đổi.
• Thêm mới.
• Xóa.

Nhờ đó bạn biết chính xác nội dung nào sắp được commit.

Bước 4: Viết commit message

Viết message mô tả rõ thay đổi API.

Nên dùng:

Add 404 response for getOrder

Hoặc:

Update Order status enum

Không nên dùng:

Update

Message rõ ràng giúp reviewer và người vận hành sau này hiểu thay đổi trong lịch sử Git.

Bước 5: Push lên branch

Push commit đến branch đang theo dõi. Sau đó:

• Đồng đội có thể thấy thay đổi trong repo.
• CI có thể chạy lint, contract test hoặc codegen.
• Pull request có thể được review như code bình thường.

Bước 6: Xác nhận trạng thái đồng bộ

Kiểm tra trạng thái “Đã đồng bộ ngay bây giờ”. Khi trạng thái này xuất hiện, chỉnh sửa cục bộ và branch remote đã khớp nhau.

Vòng lặp hoàn chỉnh là:

Pull → Edit → Commit → Push → Verify

Không cần export. Không cần copy đặc tả giữa nhiều công cụ. Không có nguồn chân lý thứ hai.

Chế độ ưu tiên đặc tả so với Chế độ ưu tiên thiết kế

Apidog hỗ trợ hai cách làm việc. Khác biệt chính nằm ở nơi lưu đặc tả và cách chỉnh sửa.

Tiêu chí	Chế độ ưu tiên đặc tả (beta)	Chế độ ưu tiên thiết kế
Lưu trữ đặc tả	Tệp YAML/JSON thô trong Git	Dự án đám mây Apidog
Trình chỉnh sửa chính	Editor mã kiểu IDE	UI trực quan dựa trên form
Kiểm soát phiên bản	Git gốc: commit, branch, diff	Lịch sử và branch của Apidog
Đồng bộ Git hai chiều	Có: GitHub, GitLab, Azure DevOps	Thông qua export/import
Phù hợp nhất cho	Nhóm làm việc nhiều với Git	Nhóm thích workflow trực quan

Không có chế độ nào luôn tốt hơn. Nếu review và release của bạn đã chạy trên Git, Chế độ ưu tiên đặc tả giúp giảm bước trung gian. Nếu nhóm thiết kế API chủ yếu bằng UI và ít chỉnh sửa OpenAPI thô, Chế độ ưu tiên thiết kế có thể phù hợp hơn.

Khi nào nên dùng Chế độ ưu tiên đặc tả?

Chọn Chế độ ưu tiên đặc tả khi:

• Đặc tả API cần đi qua pull request và code review.
• Bạn muốn dùng git blame, git log và diff thực sự cho hợp đồng API.
• CI cần chạy spec linting, contract test hoặc code generation từ tệp trên đĩa.
• Nhiều kỹ sư cùng chỉnh sửa đặc tả và cần diff rõ ràng, dễ merge.
• Bạn muốn loại bỏ bước export/import giữa các công cụ.

Tiếp tục dùng workflow trực quan, ưu tiên cloud nếu nhóm của bạn thiết kế API mà không viết OpenAPI thô, hoặc nếu người sở hữu đặc tả không phải kỹ sư và thích editor dạng form.

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

Quy trình làm việc API bản địa Git là gì?

Đó là cách lưu đặc tả OpenAPI dưới dạng tệp trong repo Git và quản lý mọi thay đổi bằng commit, branch và pull request. Đặc tả đi qua cùng quy trình kiểm soát phiên bản và review như mã ứng dụng.

Chế độ ưu tiên đặc tả của Apidog có hỗ trợ GitHub và GitLab không?

Có. Chế độ ưu tiên đặc tả đồng bộ hai chiều trực tiếp với GitHub và GitLab. Azure DevOps được hỗ trợ thông qua Git Connection. Bạn kết nối repo, chọn branch, rồi Apidog giữ workspace và remote luôn đồng bộ.

Tôi có thể chỉnh sửa OpenAPI dưới dạng YAML hoặc JSON thô không?

Có. Bạn chỉnh sửa trực tiếp YAML/JSON trong editor kiểu IDE, với syntax highlight, schema validation và autocomplete cho OpenAPI/Swagger. Sidebar outline giúp điều hướng nhanh trong các đặc tả lớn.

Khác biệt giữa Chế độ ưu tiên đặc tả và Chế độ ưu tiên thiết kế là gì?

Chế độ ưu tiên đặc tả giữ OpenAPI dưới dạng tệp trong Git và chỉnh sửa bằng code editor với đồng bộ hai chiều. Chế độ ưu tiên thiết kế giữ đặc tả trong dự án đám mây Apidog và dùng editor trực quan dựa trên form.

Kết luận

Quy trình API bản địa Git đưa hợp đồng API về cùng nơi với mã nguồn. Đặc tả trở thành một tệp, tệp trở thành commit, và commit đi qua quy trình review mà nhóm đã sử dụng hằng ngày.

Chế độ ưu tiên đặc tả của Apidog cung cấp editor kiểu IDE, outline có thể điều hướng và đồng bộ Git hai chiều để triển khai workflow này. Bạn chỉnh sửa YAML/JSON thô, commit message rõ ràng, push lên repo và xác nhận trạng thái “Đã đồng bộ ngay bây giờ”.

Hãy thử Chế độ ưu tiên đặc tả và đưa đặc tả API của bạn về với Git.