Đồng Bộ OpenAPI Spec Lên GitHub: 2 Cách Đơn Giản

Nếu tài liệu OpenAPI của bạn nằm trong Git nhưng bạn lại chỉnh sửa nó trong một API client, quy trình thường rất dễ lỗi: sao chép YAML, dán lại vào repo, kiểm tra xem có ai vừa sửa cùng tệp không, rồi hy vọng quá trình import/export không làm mất trường nào. Cách làm thủ công này nhanh chóng trở thành điểm nghẽn khi nhóm cần cập nhật đặc tả API thường xuyên.

Dùng thử Apidog ngay hôm nay

Bài viết này hướng dẫn cách đồng bộ đặc tả OpenAPI với GitHub bằng Chế độ Spec-First của Apidog. Mục tiêu là để tệp OpenAPI trong repo và nội dung bạn chỉnh sửa trong Apidog luôn là cùng một nguồn dữ liệu, thay vì hai bản sao phải đối chiếu thủ công. Bạn sẽ kết nối Git provider, mở project từ repo, chỉnh sửa YAML, commit và push ngược lại GitHub. Các bước tương tự cũng áp dụng cho GitLab.

Đồng bộ hai chiều nghĩa là gì?

Đồng bộ hai chiều nghĩa là thay đổi có thể đi theo cả hai hướng mà không cần export/import thủ công:

• Apidog → Git: bạn chỉnh sửa OpenAPI trong Apidog, commit, rồi push thay đổi lên nhánh đã chọn như một Git commit bình thường.
• Git → Apidog: nếu đồng nghiệp chỉnh sửa tệp OpenAPI trong repo, Apidog kéo thay đổi đó về để editor phản ánh đúng trạng thái của nhánh remote.

Trong workflow này, repo Git là source of truth. Apidog đóng vai trò là trình chỉnh sửa trực quan và code editor nằm trên repo. Đây là ý tưởng cốt lõi của quy trình làm việc API Git-native: đặc tả API được versioning, review và theo dõi lịch sử giống như các tệp khác trong codebase.

Điều kiện tiên quyết

Trước khi bắt đầu, hãy chuẩn bị:

• Tài khoản Apidog và ứng dụng Apidog desktop hoặc web.
• Repo GitHub hoặc GitLab có chứa tài liệu OpenAPI, hoặc repo mà bạn có quyền ghi.
• Chế độ Spec-First (beta) đã được bật.
• Quyền ghi trên nhánh bạn muốn đồng bộ.

Nếu bạn chỉ có quyền đọc, bạn có thể kéo đặc tả về nhưng không thể push thay đổi lên remote.

Bước 1: Kết nối Git provider

Đầu tiên, cấp quyền để Apidog truy cập Git provider của bạn.

1. Mở Apidog.
2. Tạo project mới.
3. Chọn Spec-First Mode.
4. Khi được hỏi nguồn dữ liệu, chọn GitHub hoặc GitLab.
5. Nhấn Authorize.
6. Hoàn tất OAuth trong trình duyệt.
7. Chọn phạm vi repo mà Apidog được phép truy cập.

Trên GitHub, bạn có thể giới hạn quyền truy cập vào một số repo cụ thể thay vì cấp quyền cho toàn bộ tài khoản.

Sau khi ủy quyền xong, Apidog sẽ quay lại màn hình tạo project với provider đã kết nối. Bạn chỉ cần làm bước này một lần cho mỗi provider; các project sau có thể dùng lại kết nối đó.

Tài liệu đầy đủ về Spec-First Mode, bao gồm Azure DevOps thông qua Git Connection, có tại tài liệu Chế độ Spec-First.

Bước 2: Tạo project từ repo và nhánh

Tiếp theo, trỏ Apidog đến repo chứa tệp OpenAPI.

1. Chọn Git provider đã kết nối.
2. Chọn repo chứa đặc tả OpenAPI.
3. Chọn nhánh cần đồng bộ, ví dụ: main.
4. Xác nhận đường dẫn đến tệp OpenAPI nếu Apidog yêu cầu, ví dụ:
   • openapi.yaml
   • docs/openapi.yaml
   • api/openapi.yml
5. Tạo project.

Apidog sẽ clone đặc tả từ nhánh đã chọn và mở nó trong editor. Thanh bên trái hiển thị các endpoint, schema và thành phần OpenAPI đã được parse từ YAML.

Từ thời điểm này, bạn đang chỉnh sửa trực tiếp đặc tả nằm trong repo, không phải một bản sao tách biệt.

Bước 3: Chỉnh sửa OpenAPI YAML trong code editor

Spec-First Mode cung cấp editor kiểu IDE cho tệp OpenAPI YAML, bao gồm:

• Syntax highlighting.
• Validation nội tuyến.
• Autocomplete.
• Outline trực quan cho paths, operations và schemas.

Ví dụ, thêm endpoint kiểm tra tình trạng dịch vụ:

paths:
  /health:
    get:
      summary: Service health check
      operationId: getHealth
      responses:
        '200':
          description: Service is up
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok

Khi bạn nhập YAML, Apidog cập nhật outline ở thanh bên trái. Endpoint /health sẽ xuất hiện ngay trong cây điều hướng.

Editor cũng giúp phát hiện lỗi trước khi commit, ví dụ:

• Thiếu responses.
• Sai indentation YAML.
• $ref trỏ đến schema không tồn tại.
• Cấu trúc OpenAPI không hợp lệ.

Thay vì phát hiện lỗi trong CI pipeline sau khi push, bạn có thể sửa trực tiếp trong editor trước khi tạo commit.

Nếu bạn muốn đi sâu hơn vào diff và lịch sử thay đổi của đặc tả, xem thêm hướng dẫn về kiểm soát phiên bản OpenAPI bằng Git.

Bước 4: Commit và push thay đổi

Khi YAML đã ổn, gửi thay đổi lên GitHub.

1. Mở khu vực Git hoặc source control trong project.
2. Xem lại diff để biết chính xác phần nào đã thay đổi.
3. Nhập commit message, ví dụ:

Add /health endpoint

1. Nhấn Commit & Push.

Apidog sẽ commit vào nhánh đã chọn và push lên remote. Khi mở repo trên GitHub, bạn sẽ thấy commit mới trong lịch sử nhánh, giống như một commit Git thông thường.

Nếu bạn chưa muốn push, các thay đổi vẫn ở local trong Apidog. Bạn có thể hủy các chỉnh sửa chưa đẩy để quay lại trạng thái đồng bộ gần nhất.

Bước 5: Kiểm tra trạng thái đồng bộ

Apidog hiển thị trạng thái đồng bộ để bạn biết editor và remote branch có đang khớp nhau hay không.

Sau khi push thành công, trạng thái sẽ hiển thị kiểu như:

Synced just now

Điều này xác nhận nội dung trong editor và nhánh remote đang trùng nhau.

Theo thời gian, trạng thái có thể cập nhật thành:

Synced 5 minutes ago

Nếu người khác push thay đổi lên cùng nhánh, Apidog sẽ kéo thay đổi đó về và cập nhật lại trạng thái sau khi đồng bộ.

Nếu trạng thái báo pending, outdated hoặc có lỗi, hãy kiểm tra trước khi tiếp tục chỉnh sửa. Điều đó thường có nghĩa là bản local và remote đã lệch nhau.

Khắc phục sự cố thường gặp

Lỗi quyền hoặc token hết hạn

Nếu push thất bại do lỗi quyền:

1. Kiểm tra quyền truy cập repo.
2. Chạy lại bước authorize Git provider.
3. Đảm bảo token chưa bị thu hồi từ phía GitHub hoặc GitLab.

Chọn sai nhánh

Nếu bạn push vào main nhưng nhánh này được bảo vệ, GitHub có thể từ chối push trực tiếp.

Cách xử lý:

• Chọn một nhánh khác có thể push.
• Tạo pull request theo quy trình của team.
• Hoặc điều chỉnh branch protection rule nếu phù hợp.

Merge conflict

Nếu đồng nghiệp chỉnh sửa cùng tệp OpenAPI trong khi bạn cũng đang sửa, remote có thể đi trước bản local.

Cách xử lý giống các conflict Git khác:

1. Pull bản mới nhất.
2. Kiểm tra phần YAML bị conflict.
3. Giữ lại nội dung đúng.
4. Validate lại đặc tả.
5. Commit và push lại.

Vì OpenAPI YAML là text file, conflict có thể được xử lý tương tự source code.

Validation error

Apidog có thể cảnh báo các lỗi OpenAPI ngay trong editor. Nên xử lý các lỗi này trước khi commit, vì đặc tả không hợp lệ có thể ảnh hưởng đến:

• API documentation.
• Mock server.
• Test case.
• Code generation.
• CI pipeline.

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

Đồng bộ với GitHub có hoạt động với GitLab và Azure DevOps không?

Có. Spec-First Mode hỗ trợ trực tiếp GitHub và GitLab. Azure DevOps được hỗ trợ thông qua Git Connection. Quy trình tổng thể vẫn giống nhau: kết nối provider, mở repo, chỉnh sửa, commit và push.

Nếu đồng nghiệp sửa đặc tả trong repo khi tôi đang làm việc trong Apidog thì sao?

Apidog sẽ kéo thay đổi từ repo về trong quá trình đồng bộ hai chiều. Nếu hai thay đổi nằm ở các phần khác nhau của tệp, chúng thường sẽ merge sạch. Nếu cùng sửa một vùng YAML, bạn sẽ xử lý conflict Git tiêu chuẩn.

Tôi có thể hoàn tác thay đổi trước khi push lên GitHub không?

Có. Trước khi nhấn Commit & Push, các chỉnh sửa vẫn là local. Bạn có thể dùng chức năng hủy chỉnh sửa chưa push để quay về trạng thái đồng bộ gần nhất. Khi đó, không có thay đổi nào được gửi lên remote.