Cách kết nối Apidog với GitHub, GitLab

Nếu thông số kỹ thuật API của bạn nằm trong Apidog nhưng nguồn đáng tin cậy của bạn nằm trong Git, bạn muốn cả hai thống nhất với nhau. Tích hợp Git của Apidog sẽ thu hẹp khoảng cách đó. Nó cho phép bạn kết nối kho lưu trữ GitHub, GitLab hoặc Azure DevOps với dự án của mình, đẩy thông số kỹ thuật OpenAPI vào hệ thống kiểm soát phiên bản và kéo các thay đổi từ kho lưu trữ trở lại Apidog. Bạn sẽ có nhật ký kiểm tra rõ ràng, đánh giá mã cho các thay đổi thông số kỹ thuật và một bản sao lưu an toàn trước mọi sự cố xảy ra bên trong ứng dụng.

Đây là tài liệu tham khảo tổng quát. Nó bao gồm mọi nhà cung cấp mà Apidog hỗ trợ, cả hai cách sản phẩm giao tiếp với Git và các quyết định thực tế bạn sẽ phải đối mặt: kho lưu trữ nào, nhánh nào, ai có thể đẩy và phải làm gì khi có sự cố. Nếu bạn chỉ cần hướng dẫn tập trung vào GitHub, hãy đọc hướng dẫn chuyên biệt về cách đồng bộ thông số kỹ thuật OpenAPI của bạn với GitHub. Ở đây, chúng ta sẽ đi sâu hơn.

Tích hợp Git của Apidog làm gì

Apidog giao tiếp với Git theo hai cách riêng biệt. Chúng giải quyết các vấn đề khác nhau và bạn có thể sử dụng một, cách kia hoặc cả hai. Việc nhầm lẫn giữa chúng là nguyên nhân phổ biến nhất gây bối rối, vì vậy hãy phân biệt chúng trước tiên.

Khả năng đầu tiên là đồng bộ hai chiều thông qua Chế độ Spec-First. Bạn chỉnh sửa tài liệu OpenAPI của mình dưới dạng YAML hoặc JSON bên trong trình chỉnh sửa kiểu IDE của Apidog, cam kết các thay đổi của bạn và đẩy chúng lên nhánh đã kết nối. Khi người khác cập nhật thông số kỹ thuật trong kho lưu trữ, bạn sẽ kéo các thay đổi đó trở lại Apidog. Đây là một chu trình khép kín thực sự: các chỉnh sửa được đẩy ra Git, và các thay đổi trong kho lưu trữ được kéo trở lại.

Khả năng thứ hai là sao lưu API specs tự động bằng Git. Ở đây, Apidog xuất tệp OpenAPI/Swagger của mỗi module và đẩy nó lên kho lưu trữ theo lịch trình. Đây là tính năng một chiều và tự động. Bạn cấu hình một lần, và hệ thống sẽ giữ một bản sao được quản lý phiên bản của các specs của bạn trong Git mà bạn không cần phải động tay. Đó là một mạng lưới an toàn, chứ không phải một quy trình làm việc chỉnh sửa.

Hãy ghi nhớ sự khác biệt này trong phần còn lại của bài viết. Khi chúng tôi nói “đồng bộ”, chúng tôi muốn nói đến luồng hai chiều của Chế độ Spec-First. Khi chúng tôi nói “sao lưu”, chúng tôi muốn nói đến việc xuất dữ liệu một chiều theo lịch trình.

Các nhà cung cấp Git được hỗ trợ

Apidog hỗ trợ ba nhà cung cấp mà hầu hết các nhóm đã sử dụng. GitHub và GitLab kết nối trực tiếp thông qua các luồng ủy quyền gốc của họ. Azure DevOps kết nối thông qua một Kết nối Git chung, hoạt động với bất kỳ máy chủ Git nào hỗ trợ xác thực HTTPS tiêu chuẩn.

Kết nối Git chung là giải pháp thay thế. Nếu máy chủ của bạn không phải là GitHub hoặc GitLab theo tên, nhưng nó hỗ trợ Git tiêu chuẩn qua HTTPS với xác thực mã thông báo, thì kết nối chung thường xử lý được. Azure DevOps là trường hợp tiêu biểu, nhưng cùng một đường dẫn này cũng bao gồm các thiết lập tự lưu trữ (self-hosted) mà hiển thị URL sao chép HTTPS.

Kết nối nhà cung cấp Git của bạn

Bước kết nối là nơi bạn cấp cho Apidog quyền truy cập cần thiết để đọc và ghi vào kho lưu trữ của bạn. Cơ chế hơi khác nhau tùy thuộc vào nhà cung cấp, nhưng hình thức chung là như nhau: ủy quyền, chọn kho lưu trữ, chọn nhánh.

Đối với GitHub, bạn ủy quyền thông qua màn hình OAuth của GitHub. Apidog yêu cầu quyền truy cập kho lưu trữ để có thể đọc thông số kỹ thuật và đẩy commit. Nếu kho lưu trữ thuộc về một tổ chức, GitHub có thể chuyển yêu cầu thông qua quản trị viên tổ chức để phê duyệt quyền truy cập của bên thứ ba. Các kho lưu trữ cá nhân sẽ được ủy quyền ngay lập tức dưới tài khoản của chính bạn.

Đối với GitLab, quy trình tương tự GitHub. Bạn đăng nhập qua màn hình OAuth của GitLab và cấp quyền truy cập kho lưu trữ. GitLab tự quản lý hoạt động miễn là Apidog có thể tiếp cận phiên bản đó qua mạng.

Đối với Azure DevOps, bạn sử dụng Kết nối Git chung. Thay vì bắt tay OAuth, bạn cung cấp URL sao chép HTTPS của kho lưu trữ và một mã thông báo truy cập cá nhân (PAT). Tạo PAT trong Azure DevOps với quyền đọc và ghi mã, sau đó dán vào Apidog. Mã thông báo là thông tin xác thực cho phép Apidog đẩy commit, vì vậy hãy giới hạn phạm vi của nó chính xác vào các kho lưu trữ mà nó cần.

Một vài lưu ý về quyền hạn giúp tiết kiệm thời gian:

• Kho lưu trữ của tổ chức so với kho lưu trữ cá nhân. Các kho lưu trữ của tổ chức thường yêu cầu quản trị viên phê duyệt tích hợp một lần. Nếu ủy quyền của bạn dường như thành công nhưng Apidog không thể nhìn thấy kho lưu trữ, thường là thiếu sự phê duyệt của quản trị viên.
• Giới hạn chặt chẽ phạm vi mã thông báo. Đối với Azure DevOps và bất kỳ kết nối chung nào, hãy cấp quyền đọc/ghi mã PAT cho dự án mục tiêu mà thôi. Tránh các mã thông báo toàn quyền tài khoản.
• Kho lưu trữ riêng tư vẫn hoạt động tốt. Apidog hoạt động với các kho lưu trữ riêng tư. Quyền truy cập đến từ ủy quyền hoặc mã thông báo bạn cung cấp, chứ không phải từ khả năng hiển thị công khai.

Sau khi nhà cung cấp được kết nối, bạn tạo dự án Apidog từ một kho lưu trữ cùng với một nhánh, thường là main. Sự kết hợp đó là điều ràng buộc các thông số kỹ thuật của bạn với một vị trí cụ thể trong hệ thống kiểm soát phiên bản. Nếu bạn mới làm quen với thực tiễn rộng hơn, hướng dẫn của chúng tôi về kiểm soát phiên bản OpenAPI bằng Git bao gồm các quy ước đáng áp dụng trước khi bạn thiết lập mọi thứ.

Đồng bộ hai chiều với Chế độ Spec-First

Chế độ Spec-First là nơi thực hiện đồng bộ hai chiều. Nó biến Apidog thành một trình chỉnh sửa spec có thể commit vào Git giống như bất kỳ mã nào khác. Bạn có thể đọc tài liệu tham khảo đầy đủ trong tài liệu chính thức của Apidog; đây là cách chu trình làm việc trong thực tế.

Bạn chỉnh sửa tài liệu OpenAPI trực tiếp dưới dạng YAML hoặc JSON. Trình chỉnh sửa có phong cách IDE: nó cung cấp tính năng tô sáng cú pháp, xác thực trực tiếp và tự động hoàn thành, vì vậy một $ref bị định dạng sai hoặc một trường bắt buộc bị thiếu sẽ hiển thị ngay khi bạn gõ chứ không phải sau khi bạn đẩy. Khi bạn chỉnh sửa, thanh bên trái sẽ tự động phân tích tài liệu thành dàn ý, đường dẫn, thao tác và lược đồ, giúp bạn điều hướng một thông số kỹ thuật lớn mà không cần cuộn qua văn bản thô.

Một chỉnh sửa điển hình trông như thế này. Giả sử bạn thêm một điểm cuối:

paths:
 /v1/orders/{orderId}:
 get:
 operationId: getOrder
 summary: Retrieve a single order
 parameters:
 - name: orderId
 in: path
 required: true
 schema:
 type: string
 responses:
 '200':
 description: The requested order
 content:
 application/json:
 schema:
 $ref: '#/components/schemas/Order'

Khi bạn lưu thay đổi đó, Apidog sẽ đánh dấu nó là một chỉnh sửa cục bộ. Sau đó, bạn commit với một thông báo và đẩy lên nhánh đã kết nối, chính xác như bạn làm với bất kỳ quy trình làm việc Git nào. Sau khi đẩy thành công, một chỉ báo đồng bộ hóa sẽ hiển thị “Đã đồng bộ hóa gần đây” để xác nhận rằng Apidog và nhánh giữ cùng một nội dung.

Hướng kéo cũng quan trọng không kém. Khi một đồng đội chỉnh sửa thông số kỹ thuật trong kho lưu trữ và đẩy lên, bạn sẽ kéo những thay đổi đó vào Apidog để cập nhật bản sao cục bộ của mình. Điều này làm cho sự tích hợp thực sự hai chiều: kho lưu trữ không chỉ là mục tiêu sao lưu mà còn là một ngang hàng.

Nếu bạn thực hiện các chỉnh sửa mà bạn không muốn giữ lại, bạn có thể loại bỏ các chỉnh sửa chưa đẩy trước khi commit. Điều đó sẽ đưa bản sao làm việc của bạn trở lại trạng thái đồng bộ cuối cùng, rất tiện lợi khi bạn thử nghiệm và quyết định rằng thay đổi đó không đáng giữ lại.

Nhịp điệu commit và đẩy này là cốt lõi của quy trình làm việc API nguyên bản Git các thay đổi thông số kỹ thuật trải qua cùng một cơ chế xem xét, lịch sử và hoàn nguyên như phần còn lại của cơ sở mã của bạn. Người đánh giá nhận xét về sự khác biệt YAML trong một pull request, các phê duyệt kiểm soát việc hợp nhất, và lịch sử thiết kế API của bạn đọc giống như lịch sử mã của bạn.

Sao lưu Git tự động các thông số kỹ thuật API

Tính năng sao lưu là một nửa "ít ồn ào" hơn của tích hợp Git của Apidog, và nó gần như không yêu cầu gì từ bạn sau khi cài đặt. Bạn chỉ cần trỏ một module vào một kho lưu trữ, và Apidog sẽ xử lý phần còn lại.

Đây là cơ chế. Apidog có thể sao lưu tệp OpenAPI/Swagger cho mỗi module vào kho lưu trữ Git, GitHub, GitLab và Azure DevOps đều được hỗ trợ. Sau khi bạn lưu cấu hình sao lưu, hệ thống sẽ tự động đẩy tệp OpenAPI Spec của module vào kho lưu trữ đã chỉ định. Việc đẩy diễn ra trong một khung thời gian ngẫu nhiên ngoài giờ cao điểm vào ban đêm, giúp nó không ảnh hưởng đến giờ làm việc của bạn và phân tán tải.

Những gì được lưu trữ là tài liệu OpenAPI/Swagger được xuất của module đó, một bản sao của hợp đồng API như hiện tại. Bởi vì mỗi lần đẩy là một commit, bạn sẽ tích lũy lịch sử phiên bản trong Git. Bạn có thể so sánh hợp đồng của tuần trước với hợp đồng hôm nay, xem chính xác khi nào một trường thay đổi và khôi phục phiên bản trước đó trực tiếp từ kho lưu trữ nếu bạn cần.

Luồng sao lưu được thiết kế là một chiều. Apidog ghi vào kho lưu trữ; nó không đọc các thay đổi trở lại từ đó. Nếu bạn muốn các chỉnh sửa của kho lưu trữ được đưa vào Apidog, đó là công việc của Chế độ Spec-First, không phải của sao lưu. Hãy sử dụng sao lưu khi mục tiêu của bạn là độ bền và lịch sử mà không thay đổi cách nhóm của bạn làm việc hàng ngày.

Chọn cấu trúc nhánh và kho lưu trữ

Các quyết định cấu trúc bạn đưa ra ban đầu sẽ định hình mức độ mượt mà của quá trình tích hợp sau này. Hai câu hỏi chính: nhánh nào, và bao nhiêu kho lưu trữ.

Lựa chọn nhánh. Hầu hết các nhóm đồng bộ hóa với main cho thông số kỹ thuật chuẩn và sử dụng các nhánh tính năng (feature branches) cho thiết kế đang trong quá trình thực hiện. Việc trỏ Apidog vào một nhánh tính năng cho phép bạn lặp lại các thay đổi thông số kỹ thuật một cách độc lập, mở một pull request và hợp nhất sau khi đánh giá đã được thông qua, thiết kế API của bạn tuân theo cùng một mô hình phân nhánh như mã của bạn. Trỏ Apidog trực tiếp vào main đơn giản hơn nhưng bỏ qua cổng đánh giá, vì vậy hãy dành nó cho các nhóm nhỏ hoặc các thay đổi rủi ro thấp.

Một kho lưu trữ hay nhiều kho lưu trữ. Không có câu trả lời đúng duy nhất, nhưng những sự đánh đổi là rõ ràng:

• Một kho lưu trữ cho mỗi API giúp lịch sử của mỗi spec rõ ràng và kiểm soát quyền truy cập chặt chẽ. Đây là lựa chọn tự nhiên khi các nhóm khác nhau sở hữu các API khác nhau.
• Một monorepo cho tất cả các spec tập trung mọi thứ và đơn giản hóa việc tìm kiếm và xem xét giữa các API. Nó hoạt động tốt khi một nhóm nền tảng sở hữu toàn bộ bề mặt API. Chỉ cần giữ cấu trúc thư mục dễ đoán, một thư mục cho mỗi module, để các bản sao lưu và đồng bộ không xung đột.

Nếu bạn sử dụng một monorepo, hãy cung cấp cho mỗi module một đường dẫn riêng. Điều đó giúp các bản sao lưu tự động gọn gàng và làm cho các bản diff spec dễ đọc trong quá trình xem xét.

Quyền và truy cập của nhóm

Tích hợp Git liên quan đến thông tin xác thực, vì vậy cần phải cân nhắc kỹ lưỡng về việc ai có thể làm gì. Quyền hạn tồn tại ở hai nơi: bên trong Apidog và bên trong nhà cung cấp Git của bạn.

Bên trong Apidog, quyền hạn của nhóm được cấu hình trong quá trình thiết lập dự án. Đó là nơi bạn quyết định ai có thể đồng bộ hóa và đẩy lên kho lưu trữ đã kết nối. Giới hạn quyền đẩy cho những người sở hữu thông số kỹ thuật và cho phép những người khác đọc. Điều này ngăn chặn các lần đẩy vô ý từ những người đóng góp chỉ đang duyệt thiết kế API.

Bên trong nhà cung cấp Git của bạn, thông tin xác thực rất quan trọng. Đối với GitHub và GitLab, ủy quyền OAuth mang theo quyền truy cập của người dùng đã cấp. Đối với Azure DevOps và các kết nối chung, mã thông báo truy cập cá nhân là thông tin xác thực, hãy coi nó như một bí mật. Đừng dán mã thông báo vào các tài liệu được chia sẻ, chỉ giới hạn phạm vi của chúng cho các kho lưu trữ mục tiêu và xoay vòng chúng theo cùng một tần suất bạn xoay vòng các bí mật khác. Nếu ai đó rời nhóm, hãy thu hồi mã thông báo của họ và ủy quyền lại dưới một tài khoản vẫn đang hoạt động.

Nguyên tắc rất đơn giản: tính năng tích hợp chỉ được bảo mật chặt chẽ như mã thông báo yếu nhất đằng sau nó. Giữ phạm vi hẹp và quyền sở hữu rõ ràng.

Xử lý xung đột hợp nhất và sai lệch

Vì Apidog commit lịch sử Git thực, nó kế thừa mô hình xung đột của Git và các công cụ của Git để giải quyết nó. Xung đột xảy ra khi hai người thay đổi cùng một phần của spec trước khi đồng bộ hóa.

Hãy hình dung kịch bản. Bạn chỉnh sửa lược đồ Order trong Apidog và đẩy lên. Một đồng đội đã chỉnh sửa cùng lược đồ đó ở phía kho lưu trữ và đẩy lên trước. Khi bạn cố gắng hòa giải, Git sẽ đánh dấu xung đột trên YAML, vì cả hai bên đã thay đổi các dòng chồng chéo. Đây không phải là vấn đề của Apidog; đây là xung đột hợp nhất Git thông thường trên một tệp YAML, và bạn giải quyết nó theo cách thông thường.

Để tránh xung đột, hãy kéo trước khi đẩy. Việc đưa trạng thái kho lưu trữ mới nhất vào Apidog trước khi cam kết các thay đổi của riêng bạn sẽ giữ cho bản sao làm việc của bạn luôn cập nhật và thu hẹp khoảng thời gian mà hai chỉnh sửa va chạm. Khi xảy ra xung đột, hãy giải quyết nó trên YAML giống như cách bạn giải quyết bất kỳ xung đột hợp nhất nào: chọn các dòng chính xác, giữ cho tài liệu hợp lệ và đồng bộ hóa lại. Tính năng xác thực trực tiếp của trình chỉnh sửa rất hữu ích ở đây, một lần hợp nhất thất bại làm hỏng cấu trúc OpenAPI sẽ hiển thị ngay lập tức chứ không phải sau khi bạn đẩy.

Sự sai lệch (Drift), khi Apidog và kho lưu trữ âm thầm khác nhau, là phiên bản chậm hơn của cùng một vấn đề. Chỉ báo “Đã đồng bộ hóa gần đây” là cảnh báo sớm của bạn. Nếu nó không hiển thị đã đồng bộ, có điều gì đó chưa được đẩy hoặc chưa được kéo. Hãy coi đó là lời nhắc để điều chỉnh trước khi khoảng cách trở nên lớn hơn.

Khắc phục sự cố

Hầu hết các vấn đề tích hợp đều bắt nguồn từ xác thực, lựa chọn nhánh hoặc đồng bộ hóa bị gián đoạn. Hãy xem xét bảng dưới đây trước khi cho rằng có điều gì đó nghiêm trọng hơn.

Nếu ủy quyền là vấn đề lặp đi lặp lại, và thường là như vậy, hãy bắt đầu bằng cách xác nhận rằng thông tin xác thực còn hiệu lực và có phạm vi đúng. Một mã thông báo bị thu hồi hoặc thiếu phê duyệt của tổ chức giải thích phần lớn các báo cáo “nó vừa ngừng hoạt động”.

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

Đồng bộ hóa là một chiều hay hai chiều?

Điều đó phụ thuộc vào tính năng bạn đang sử dụng. Chế độ Spec-First là hai chiều: bạn đẩy các chỉnh sửa vào Git và kéo các thay đổi từ kho lưu trữ trở lại Apidog. Tính năng sao lưu tự động là một chiều: Apidog xuất thông số kỹ thuật của từng module vào kho lưu trữ theo lịch trình và không đọc lại các thay đổi.

Thông số kỹ thuật của tôi được lưu trữ ở đâu?

Trong kho lưu trữ Git mà bạn kết nối. Đối với Chế độ Spec-First, tài liệu OpenAPI của bạn nằm trên nhánh bạn đẩy tới. Đối với sao lưu tự động, tệp OpenAPI/Swagger được xuất của mỗi module được commit vào kho lưu trữ bạn đã cấu hình. Trong cả hai trường hợp, Git giữ bản sao có phiên bản, và bạn giữ quyền kiểm soát hoàn toàn kho lưu trữ.

Tôi nên đồng bộ hóa với nhánh nào?

Sử dụng main cho thông số kỹ thuật chuẩn và các nhánh tính năng (feature branches) cho các thay đổi đang trong quá trình thực hiện. Đồng bộ hóa với một nhánh tính năng cho phép một thay đổi thông số kỹ thuật đi qua một pull request và đánh giá trước khi nó được hợp nhất, điều này phản ánh cách mã của bạn đã di chuyển qua Git.

Điều gì xảy ra nếu mã thông báo của tôi bị thu hồi?

Các lần đẩy sẽ bắt đầu thất bại vì Apidog không còn quyền ghi. Hãy ủy quyền lại nhà cung cấp, hoặc, đối với Azure DevOps và các kết nối chung, tạo một mã thông báo truy cập cá nhân mới và cập nhật nó trong Apidog. Sau khi thông tin xác thực được khôi phục, đồng bộ hóa và sao lưu sẽ tiếp tục bình thường.

Kết luận

Tích hợp Git của Apidog cung cấp cho bạn hai công cụ bổ sung: đồng bộ hóa hai chiều thông qua Chế độ Spec-First dành cho các nhóm xem spec là mã, và sao lưu tự động từng module dành cho bất kỳ ai chỉ muốn một mạng lưới an toàn có phiên bản. Cả hai đều hoạt động trên GitHub, GitLab và Azure DevOps, vì vậy bạn kết nối nhà cung cấp mà bạn đã sử dụng thay vì phải áp dụng một cái mới.

Chọn tính năng phù hợp với mục tiêu của bạn. Nếu bạn muốn xem xét và lịch sử trên mọi thay đổi thông số kỹ thuật, hãy thiết lập Chế độ Spec-First và áp dụng nhịp điệu commit-và-đẩy. Nếu bạn muốn độ bền mà không thay đổi quy trình làm việc của mình, hãy bật tính năng sao lưu và để việc đẩy hàng đêm xử lý. Nhiều nhóm sử dụng cả hai. Khi bạn sẵn sàng kết nối, hãy kết nối nhà cung cấp của bạn, trỏ một dự án vào một kho lưu trữ và nhánh, và để các thông số kỹ thuật API của bạn tồn tại ở nơi phần còn lại công việc của bạn đã có.