Kiểm Soát Phiên Bản OpenAPI Spec Với Git Như Thế Nào?

Đặc tả OpenAPI của bạn là một hợp đồng. Khi hợp đồng này thay đổi mà không được kiểm soát, client có thể lỗi, mock server trở nên sai lệch, và test vẫn pass dù API thực tế đã khác. Cách xử lý đúng là đưa openapi.yaml vào Git, tạo nhánh cho từng thay đổi, review bằng pull request và xác thực tự động bằng CI.

Thử Apidog ngay hôm nay

Bài viết này hướng dẫn quy trình kiểm soát phiên bản OpenAPI bằng Git: đặt file ở đâu, đặt tên nhánh thế nào, review diff đặc tả ra sao, thêm CI validation, và commit/push thay đổi trực tiếp từ Apidog.

Tại sao cần kiểm soát phiên bản đặc tả OpenAPI?

Một đặc tả nằm trong wiki hoặc ổ đĩa chia sẻ không có lịch sử rõ ràng. Khi payload của POST /orders thay đổi, bạn khó biết ai đã đổi, đổi khi nào, và vì sao.

Đưa openapi.yaml vào Git giúp bạn có:

• Lịch sử thay đổi: mỗi thay đổi là một commit có tác giả, thời gian và thông báo.
• Blame: dùng git blame openapi.yaml để biết ai đã thêm một field hoặc endpoint.
• Rollback: nếu một merge làm hỏng hợp đồng API, revert commit để quay lại đặc tả ổn định.
• Review: mọi thay đổi hợp đồng đi qua pull request trước khi được merge.

Đây là nền tảng của quy trình làm việc API Git-native: đặc tả là mã nguồn, và mã nguồn cần nằm trong Git.

Đặt file OpenAPI ở đâu trong repo?

Hãy chọn một vị trí đơn giản, dễ đoán và dùng nhất quán trong toàn team.

Cách phổ biến nhất:

my-service/
├── api/
│   └── openapi.yaml
├── src/
└── README.md

Hoặc nếu repo chỉ phục vụ một service API, bạn có thể đặt ở root:

my-service/
├── openapi.yaml
├── src/
└── README.md

Nếu bạn duy trì nhiều major version song song, hãy tách theo phiên bản:

api/
├── api-v1.yaml
└── api-v2.yaml

Cách này giúp cô lập thay đổi gây phá vỡ. api-v1.yaml tiếp tục phục vụ client hiện tại, trong khi api-v2.yaml có thể phát triển độc lập.

Quy ước nên được ghi rõ trong README.md, ví dụ:

## API specification

OpenAPI specification is stored at:

- `api/openapi.yaml`

All API contract changes must be submitted through pull requests.

Điều quan trọng là tránh có nhiều file cùng tự nhận là “đặc tả chính thức”. Đây cũng là nguyên tắc cốt lõi của đặc tả API dưới dạng mã.

Tạo nhánh cho thay đổi đặc tả

Bạn không cần mô hình branching riêng cho OpenAPI. Hãy dùng cùng quy trình với code:

git checkout main
git pull
git checkout -b api/add-refunds

Sau đó chỉnh openapi.yaml, commit và mở pull request.

Một số quy ước đặt tên nhánh dễ đọc:

Loại thay đổi	Mẫu	Ví dụ
Endpoint mới	api/add-<resource>	api/add-refunds
Thay đổi field	api/change-<resource>-<field>	api/change-order-status
Thay đổi gây phá vỡ	api/breaking-<description>	api/breaking-v2-auth
Sửa lỗi / dọn dẹp	api/fix-<description>	api/fix-pagination-schema

Tiền tố api/ giúp reviewer nhận ra PR này chạm đến hợp đồng API. Với thay đổi gây phá vỡ, tiền tố breaking- là tín hiệu để review kỹ hơn và cân nhắc tăng version.

Giữ nhánh ngắn hạn. Một nhánh đặc tả tồn tại quá lâu dễ xung đột với thay đổi của người khác. Mỗi PR nên xử lý một thay đổi logic duy nhất.

Review thay đổi OpenAPI trong pull request

Một PR đặc tả là một thay đổi hợp đồng. Reviewer không chỉ kiểm tra YAML hợp lệ, mà còn cần kiểm tra tác động lên client.

Viết YAML thân thiện với diff

Ưu tiên định dạng rõ ràng, mỗi thuộc tính trên một dòng:

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

Khi format nhất quán, việc thêm hoặc sửa một field sẽ tạo diff nhỏ, dễ review.

Checklist review PR đặc tả

Reviewer nên kiểm tra:

• Thay đổi gây phá vỡ

  • Có thêm field bắt buộc vào request không?
  • Có xóa hoặc đổi tên field trong response không?
  • Có đổi type dữ liệu không?
  • Có xóa giá trị khỏi enum không?

• Khả năng tương thích ngược

  • Endpoint mới thường an toàn.
  • Field optional mới thường an toàn.
  • Thay đổi cấu trúc response hiện có có thể phá client.

• Đặt tên và tính nhất quán

  • Path có nhất quán với API hiện tại không?
  • Resource dùng số ít hay số nhiều?
  • Field name dùng camelCase, snake_case hay quy ước khác?

• Độ hoàn chỉnh

  • Operation có summary không?
  • Có schema response không?
  • Có mô tả lỗi phổ biến như 400, 401, 404, 500 không?

• Ví dụ

  • Request/response example có thực tế không?
  • Mock server và documentation có dùng được từ example không?

Ví dụ một phần schema có example:

components:
  schemas:
    Order:
      type: object
      required:
        - id
        - status
      properties:
        id:
          type: string
          example: "ord_123"
        status:
          type: string
          enum:
            - pending
            - paid
            - cancelled
          example: "paid"

Đừng chỉ dựa vào mắt thường để phát hiện breaking change. Hãy thêm kiểm tra tự động trong CI.

Commit và push từ Apidog

Bạn vẫn có thể sửa YAML bằng tay, nhưng một editor trực quan có validation trực tiếp sẽ giúp giảm lỗi cú pháp và lỗi schema.

Chế độ Spec-First của Apidog hỗ trợ đồng bộ Git hai chiều:

1. Kết nối repo Git với Apidog.
2. Trỏ Apidog đến file đặc tả, ví dụ api/openapi.yaml.
3. Chỉnh endpoint, schema và example trong editor trực quan.
4. Apidog ghi lại YAML nhất quán, thân thiện với diff.
5. Commit trên nhánh.
6. Push lên repo.
7. Mở pull request như quy trình Git bình thường.

Vì Apidog serialize YAML nhất quán, diff sẽ ít bị nhiễu bởi việc sắp xếp lại hoặc format lại không cần thiết. Bạn có thể xem hướng dẫn thiết lập trong tài liệu Chế độ Spec-First của Apidog. Nếu bạn muốn đồng bộ với GitHub, hãy xem thêm bài viết về đồng bộ hóa đặc tả OpenAPI với GitHub.

Thêm validation bằng CI

Không nên để một đặc tả không hợp lệ được merge vào main. Hãy chạy lint và validation trong pull request.

Ví dụ GitHub Actions tối thiểu với Redocly CLI:

name: Validate OpenAPI

on: [pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Lint OpenAPI spec
        run: npx @redocly/cli lint api/openapi.yaml

Bạn có thể thêm kiểm tra parsing OpenAPI 3.x:

name: Validate OpenAPI

on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Lint spec
        run: npx @redocly/cli lint api/openapi.yaml

      - name: Bundle spec
        run: npx @redocly/cli bundle api/openapi.yaml -o /tmp/openapi.bundle.yaml

Các kiểm tra nên có trong CI:

• Lint cấu trúc đặc tả.
• Xác thực đặc tả parse được thành OpenAPI hợp lệ.
• So sánh với main để phát hiện breaking change.
• Fail build nếu có thay đổi không tương thích.

Ví dụ dùng oasdiff để kiểm tra breaking change:

name: Check OpenAPI breaking changes

on: [pull_request]

jobs:
  breaking-changes:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install oasdiff
        run: |
          curl -fsSL https://raw.githubusercontent.com/oasdiff/oasdiff/main/install.sh | sh

      - name: Compare with main
        run: |
          git show origin/main:api/openapi.yaml > /tmp/openapi-main.yaml
          oasdiff breaking /tmp/openapi-main.yaml api/openapi.yaml

Mục tiêu là để PR tự động fail khi có breaking change không được xử lý rõ ràng.

Các thực hành tốt nhất

Áp dụng các thói quen sau để quy trình Git cho OpenAPI ổn định lâu dài:

• Dùng semantic versioning
  • Cập nhật info.version.
  • Breaking change nên tăng major version.
  • Thay đổi tương thích ngược có thể tăng minor version.

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

• Duy trì changelog
  • Đặt CHANGELOG.md cạnh file đặc tả.
  • Ghi ngắn gọn thay đổi quan trọng giữa các version.

# Changelog

## 2.1.0

- Added `GET /refunds`
- Added optional `refundReason` field

## 2.0.0

- Breaking: changed authentication scheme

• Giữ PR nhỏ

  • Một PR chỉ nên có một thay đổi logic.
  • PR lớn dễ che giấu breaking change.

• Viết commit message rõ ràng
  
  

git commit -m "Add refundReason to refund request schema"

Tốt hơn nhiều so với:

git commit -m "update spec"

• Không sửa trực tiếp trên main
  • Kể cả sửa lỗi chính tả cũng nên tạo nhánh và mở PR.
  • Điều này giữ lịch sử review nhất quán.

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

Làm thế nào để phát hiện breaking change trong đặc tả OpenAPI?

Chạy công cụ so sánh đặc tả trong CI để so sánh pull request với phiên bản trên main. Các công cụ như oasdiff có thể phân loại thay đổi là breaking, non-breaking hoặc unclassified, sau đó fail build nếu phát hiện breaking change.

Các lỗi thường được phát hiện gồm:

• Xóa field trong response.
• Thêm request parameter bắt buộc.
• Đổi type dữ liệu.
• Xóa giá trị enum.
• Đổi schema của endpoint hiện có.

Nên giữ một file OpenAPI hay chia thành nhiều file?

Hãy bắt đầu với một file openapi.yaml. Đây là cách dễ review và dễ quản lý nhất.

Khi đặc tả lớn hơn hoặc bạn duy trì nhiều major version, hãy cân nhắc:

api/
├── api-v1.yaml
└── api-v2.yaml

Hoặc tách schema bằng $ref:

components:
  schemas:
    Order:
      $ref: "./schemas/order.yaml"

Đừng chia nhỏ quá sớm. Một file rõ ràng thường tốt hơn nhiều file bị phân mảnh.

Có thể kiểm soát phiên bản đặc tả mà không cần viết YAML bằng tay không?

Có. Chế độ Spec-First của Apidog cho phép bạn chỉnh đặc tả bằng editor trực quan và đồng bộ thay đổi với Git theo hai chiều. Bạn vẫn có lịch sử commit, pull request, review và CI validation, nhưng không cần thao tác trực tiếp với YAML cho mọi thay đổi.