Đồ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 kho lưu trữ Git nhưng bạn chỉnh sửa nó bên trong một ứng dụng API client, bạn đã biết rõ sự bất tiện: sao chép YAML ra, dán lại, hy vọng không ai khác đã chạm vào tệp, và cầu mong quá trình nhập không âm thầm làm mất đi một trường. Việc giữ cho một đặc tả và một kho lưu trữ khớp nhau theo cách thủ công là một công việc vặt dễ gây lỗi chính vào lúc bạn đang vội.

Hướng dẫn này sẽ chỉ cho bạn cách đồng bộ hóa đặc tả OpenAPI của mình với GitHub bằng Chế độ Spec-First của Apidog, để đặc tả trong kho lưu trữ của bạn và đặc tả trong trình chỉnh sửa của bạn luôn là một thay vì hai bản sao mà bạn liên tục phải đối chiếu. Chúng ta sẽ kết nối một nhà cung cấp, mở một dự án trực tiếp từ kho lưu trữ, chỉnh sửa YAML và đẩy thay đổi trở lại GitHub trong một lần. Các bước tương tự cũng áp dụng cho GitLab.

Hãy bắt đầu nào.

Đồng bộ hóa hai chiều thực sự có nghĩa là gì

Đồng bộ hóa hai chiều có nghĩa là các chỉnh sửa được thực hiện theo cả hai hướng, tự động, không có bước xuất nào ở giữa.

• Apidog sang Git: Khi bạn chỉnh sửa tài liệu OpenAPI trong Apidog và commit, thay đổi sẽ được đẩy lên kho lưu trữ của bạn dưới dạng một commit Git thông thường trên nhánh bạn đã chọn.
• Git sang Apidog: Khi một đồng nghiệp (hoặc bạn, từ IDE của bạn) đẩy một thay đổi lên nhánh đó, Apidog sẽ kéo nó về để trình chỉnh sửa của bạn phản ánh những gì thực sự có trong kho lưu trữ.

Kho lưu trữ là nguồn thông tin đáng tin cậy duy nhất. Apidog là một trình chỉnh sửa phong phú nằm trên đó. Đó là toàn bộ ý tưởng đằng sau quy trình làm việc API Git-native: đặc tả được quản lý phiên bản, xem xét và theo dõi lịch sử giống như bất kỳ tệp nào khác trong cơ sở mã của bạn, thay vì nằm trong một công cụ định kỳ xuất một bản chụp nhanh.

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

Trước khi bắt đầu, hãy đảm bảo bạn có:

• Apidog đã được cài đặt (ứng dụng máy tính để bàn hoặc web), đã đăng nhập.
• Một kho lưu trữ GitHub hoặc GitLab đã chứa tài liệu OpenAPI, hoặc một kho lưu trữ mà bạn có quyền ghi. Azure DevOps cũng được hỗ trợ thông qua Git Connection.
• Chế độ Spec-First (beta) đã được bật. Đây là chế độ biến dự án của bạn thành một lớp mỏng trên một kho lưu trữ Git thay vì bộ nhớ riêng của Apidog.

Bạn sẽ cần quyền ghi trên nhánh mà bạn định đồng bộ. Quyền truy cập chỉ đọc cho phép bạn kéo nhưng không thể đẩy.

Bước 1: Kết nối nhà cung cấp Git của bạn

Đầu tiên, ủy quyền cho Apidog giao tiếp với nhà cung cấp của bạn.

1. Mở Apidog và tạo một dự án mới, chọn Chế độ Spec-First.
2. Khi được nhắc chọn nguồn, hãy chọn nhà cung cấp của bạn, GitHub hoặc GitLab.
3. Nhấp vào Authorize (Ủy quyền). Trình duyệt của bạn sẽ mở màn hình OAuth của nhà cung cấp.
4. Cấp cho Apidog quyền truy cập vào các kho lưu trữ bạn muốn đồng bộ. Trên GitHub, bạn có thể giới hạn điều này cho các kho lưu trữ cụ thể thay vì toàn bộ tài khoản của mình.

Sau khi ủy quyền hoàn tất, bạn sẽ được đưa trở lại Apidog với nhà cung cấp đã được kết nối. Bạn chỉ thực hiện điều này một lần cho mỗi nhà cung cấp, các dự án trong tương lai sẽ sử dụng lại kết nối đó.

Để tham khảo đầy đủ về quy trình này, bao gồm Azure DevOps thông qua Git Connection, hãy xem tài liệu Chế độ Spec-First.

Bước 2: Tạo dự án từ một kho lưu trữ và nhánh

Bây giờ hãy hướng Apidog đến đặc tả thực tế.

1. Với nhà cung cấp đã được kết nối, chọn kho lưu trữ chứa tệp OpenAPI của bạn.
2. Chọn nhánh để đồng bộ, thường là main. Đây là nhánh mà các commit của bạn sẽ được gửi đến và là nhánh Apidog theo dõi các thay đổi đến.
3. Xác nhận đường dẫn đến tài liệu OpenAPI nếu Apidog yêu cầu (ví dụ: openapi.yaml ở thư mục gốc của kho lưu trữ, hoặc dưới docs/).
4. Tạo dự án.

Apidog clone đặc tả từ nhánh đó và mở nó. Thanh bên trái sẽ hiển thị các điểm cuối và lược đồ của bạn, vì Apidog đã phân tích cú pháp tài liệu thành một dàn ý có thể điều hướng. Bây giờ bạn đang xem đặc tả của kho lưu trữ, trực tiếp.

Bước 3: Chỉnh sửa OpenAPI YAML của bạn trong trình chỉnh sửa mã

Chế độ Spec-First cung cấp cho bạn một trình chỉnh sửa kiểu IDE cho tệp OpenAPI YAML thô, với tô sáng cú pháp, xác thực nội tuyến và tự động hoàn thành. Bạn viết OpenAPI trực tiếp; Apidog giữ dàn ý trực quan theo từng bước khi bạn nhập.

Hãy thêm một điểm cuối nhỏ. Giả sử bạn muốn một kiểm tra tình trạng (health check):

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, hai điều xảy ra. Thanh bên trái tự động phân tích cú pháp dàn ý, vì vậy thao tác /health mới của bạn sẽ xuất hiện trong cây ngay lập tức. Và trình xác thực sẽ báo lỗi nội tuyến, một khối responses bị thiếu, một $ref bị lỗi, một lỗi thụt lề, trước khi bạn commit. Nếu YAML bị định dạng sai, bạn sẽ thấy nó được gạch chân thay vì phát hiện ra nó trong một pipeline thất bại sau này.

Đây cũng là nơi kiểm soát phiên bản phát huy tác dụng. Nếu bạn muốn tìm hiểu sâu hơn về cách các bản khác biệt (diffs) và lịch sử hoạt động trên một đặc tả, hướng dẫn về kiểm soát phiên bản OpenAPI bằng Git sẽ giải thích chi tiết.

Bước 4: Commit và push

Khi chỉnh sửa trông ổn, hãy gửi nó đến GitHub.

1. Mở bảng commit (khu vực Git/kiểm soát nguồn của dự án).
2. Xem lại thay đổi. Apidog hiển thị những gì đã được sửa đổi so với phiên bản đã đồng bộ.
3. Viết một thông điệp commit, coi nó như bất kỳ commit nào: Add /health endpoint.
4. Nhấp vào Commit & Push (Cam kết & Đẩy).

Apidog commit vào nhánh đã chọn của bạn và đẩy lên remote. Mở kho lưu trữ của bạn trên GitHub và bạn sẽ thấy commit trong lịch sử nhánh, được ghi lại như mong đợi, chỉ chạm vào tệp OpenAPI.

Bạn đổi ý trước khi đẩy? Bạn có thể hủy các chỉnh sửa chưa đẩy để đưa tài liệu trở lại trạng thái đồng bộ cuối cùng. Không có gì rời khỏi Apidog cho đến khi bạn commit, vì vậy các thử nghiệm cục bộ vẫn ở cục bộ.

Bước 5: Xác minh trạng thái đồng bộ

Apidog hiển thị một chỉ báo đồng bộ để bạn luôn biết mình đang ở đâu.

Sau khi đẩy thành công, chỉ báo sẽ hiển thị "Synced just now" (Đã đồng bộ ngay bây giờ). Đó là xác nhận của bạn rằng trình chỉnh sửa và nhánh remote giữ cùng một tài liệu. Theo thời gian, nó sẽ cập nhật ("Synced 5 minutes ago" - Đã đồng bộ 5 phút trước) và, khi ai đó khác đẩy, Apidog sẽ kéo thay đổi và đặt lại chỉ báo sau khi nó đối chiếu.

Nếu chỉ báo hiển thị trạng thái đang chờ xử lý hoặc lỗi thời, nó đang cho bạn biết bản sao cục bộ và bản remote đã phân kỳ, đó là tín hiệu để bạn kéo hoặc giải quyết trước khi tiếp tục.

Khắc phục sự cố

Một vài điều thường khiến mọi người vấp phải lần đầu.

• Quyền ủy quyền đã hết hạn hoặc bị thu hồi. Nếu các lần đẩy bắt đầu thất bại với lỗi quyền, hãy chạy lại ủy quyền từ Bước 1. Các token có thể bị thu hồi ở phía nhà cung cấp hoặc đơn giản là hết thời gian.
• Nhánh sai. Đẩy lên một nhánh main được bảo vệ yêu cầu các pull request sẽ bị từ chối. Hoặc đồng bộ với một nhánh đã có sẵn hoặc điều chỉnh các quy tắc bảo vệ của nhánh. Kiểm tra kỹ nhánh đã chọn ở Bước 2 khớp với nơi bạn mong đợi các commit sẽ đến.
• Xung đột hợp nhất (Merge conflicts). Nếu một đồng nghiệp đã đẩy lên cùng một nhánh trong khi bạn đang chỉnh sửa, remote đã đi trước bản sao cục bộ của bạn. Kéo bản mới nhất, đối chiếu YAML trùng lặp và commit lại. Vì đặc tả là văn bản thuần túy, các xung đột sẽ được giải quyết giống như bất kỳ xung đột mã nào.
• Lỗi xác thực làm gián đoạn quy trình của bạn. Apidog sẽ không ngăn bạn commit YAML không hợp lệ, nhưng bạn nên khắc phục những gì trình xác thực nội tuyến báo lỗi trước. Một đặc tả sạch sẽ giữ cho các tài liệu, mô phỏng và kiểm thử được tạo của bạn chính xác.

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

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

Có. Chế độ Spec-First hỗ trợ trực tiếp GitHub và GitLab, và Azure DevOps thông qua Git Connection. Quy trình kết nối-chỉnh sửa-commit-đẩy là giống nhau trên cả ba; chỉ có màn hình ủy quyền khác nhau tùy theo nhà cung cấp.

Điều gì xảy ra nếu một đồng nghiệp chỉnh sửa đặc tả trong kho lưu trữ trong khi tôi đang làm việc trong Apidog?

Apidog sẽ kéo thay đổi của họ vào trình chỉnh sửa của bạn như một phần của đồng bộ hóa hai chiều. Nếu các chỉnh sửa của bạn và của họ chạm vào các phần khác nhau của tệp, chúng sẽ hợp nhất một cách sạch sẽ. Nếu chúng trùng lặp, bạn sẽ giải quyết một xung đột Git tiêu chuẩn, giống như bạn làm với bất kỳ tệp văn bản nào.

Tôi có thể hoàn tác một thay đổi trước khi nó đến GitHub không?

Có. Cho đến khi bạn nhấp vào Commit & Push (Cam kết & Đẩy), các chỉnh sửa của bạn là cục bộ. Sử dụng chức năng "discard unpushed edits" (hủy các chỉnh sửa chưa đẩy) để hoàn nguyên tài liệu về trạng thái đồng bộ cuối cùng, và không có gì đến remote.