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 nó thay đổi mà không được kiểm soát, client sẽ bị lỗi, các bản mock sẽ lỗi thời, và các bài kiểm tra sẽ chạy thành công với một API không còn tồn tại. Vì vậy, hãy xử lý đặc tả này giống như phần còn lại của mã của bạn: đưa nó vào Git, tạo nhánh, xem xét và xác thực nó sau mỗi thay đổi.

Hướng dẫn này sẽ trình bày kiểm soát phiên bản OpenAPI bằng Git từ đầu đến cuối. Nơi đặt tệp, cách tạo nhánh, những gì người đánh giá thực sự tìm kiếm trong một bản diff đặc tả và cách đẩy thay đổi trực tiếp từ Apidog. Đến cuối cùng, bạn sẽ có một quy trình làm việc mà toàn bộ nhóm của bạn có thể tin cậy.

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

Một đặc tả nằm trong wiki hoặc ổ đĩa chia sẻ không có lịch sử. Bạn không thể biết ai đã thay đổi payload của POST /orders vào thứ Ba tuần trước, hoặc tại sao. Git khắc phục điều đó.

Đặt openapi.yaml dưới sự kiểm soát phiên bản và bạn sẽ nhận được bốn điều miễn phí:

• Lịch sử. Mọi thay đổi đều là một commit với tác giả, dấu thời gian và thông báo.
• Blame (Xác định tác giả). Lệnh git blame openapi.yaml cho bạn biết ai đã thêm trường bắt buộc đó và khi nào.
• Rollback (Hoàn tác). Một bản hợp nhất (merge) lỗi làm hỏng hợp đồng? Hoàn tác commit và bạn sẽ trở lại với một đặc tả hoạt động.
• Xem xét. Các thay đổi đặc tả được thực hiện thông qua pull request, vì vậy người thứ hai sẽ thấy bản diff trước khi nó được triển khai.

Đâ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 nằm trong Git.

Vị trí của tệp đặc tả trong kho lưu trữ (repo)

Hãy giữ cho nó đơn giản và dễ đoán. Hầu hết các nhóm đặt một tệp openapi.yaml duy nhất ở thư mục gốc của kho lưu trữ hoặc trong thư mục api/:

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

Khi bạn duy trì nhiều phiên bản chính song song, hãy chia theo phiên bản với một tệp cho mỗi phiên bản chính:

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

Điều này giúp cô lập các thay đổi gây phá vỡ. api-v1.yaml vẫn được giữ nguyên cho các client hiện có trong khi api-v2.yaml được phát triển. Nó cũng làm cho các bản diff nhỏ hơn và việc xem xét nhanh hơn, vì mỗi tệp thay đổi vì một lý do. Xử lý đặc tả theo cách này là ý tưởng cốt lõi đằng sau đặc tả API dưới dạng mã.

Hãy chọn một quy ước và ghi lại nó. Kết quả tồi tệ nhất là có hai tệp đều tự nhận là "đặc tả" chính thức.

Các chiến lược tạo nhánh cho thay đổi đặc tả

Bạn không cần một mô hình phân nhánh đặc biệt cho các đặc tả. Hãy tái sử dụng những gì mã của bạn đã làm. Phân nhánh từ main, thực hiện thay đổi, mở một PR.

Quy ước đặt tên giúp dễ dàng quét các nhánh đặc tả:

Tiền tố api/ báo hiệu "PR này chạm đến hợp đồng" ngay lập tức. Người đánh giá và CI có thể lọc theo nó. Đối với các thay đổi gây phá vỡ, tiền tố breaking- rõ ràng là một dấu hiệu cho thấy điều này cần được xem xét kỹ lưỡng hơn và có thể cần tăng phiên bản.

Giữ các nhánh có thời gian tồn tại ngắn. Một nhánh đặc tả tồn tại trong hai tuần sẽ xung đột với các thay đổi của những người khác. Các nhánh nhỏ, tập trung sẽ hợp nhất (merge) một cách sạch sẽ.

Xem xét các thay đổi đặc tả trong pull request

Đây là nơi kiểm soát phiên bản thể hiện giá trị của nó. Một PR đặc tả là một thay đổi hợp đồng, và các thay đổi hợp đồng xứng đáng được xem xét kỹ lưỡng.

Viết YAML theo cách thân thiện với diff để người đánh giá có thể đọc được thay đổi, chứ không phải vật lộn với định 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"

Việc thụt lề nhất quán và mỗi thuộc tính trên một dòng có nghĩa là việc thêm một trường duy nhất sẽ hiển thị dưới dạng một dòng diff. Đó là mục tiêu.

Những gì người đánh giá nên kiểm tra:

• Các thay đổi gây phá vỡ. Một trường bắt buộc có được thêm vào yêu cầu không? Một trường phản hồi có bị xóa hoặc đổi tên không? Một enum có mất giá trị không? Mỗi thay đổi đều có thể phá vỡ các client hiện có.
• Khả năng tương thích ngược. Các trường tùy chọn mới và các endpoint mới là an toàn. Các thay đổi đối với cấu trúc hiện có thì không.
• Đặt tên và tính nhất quán. Endpoint mới có khớp với cách viết hoa/thường và dạng số nhiều của phần còn lại của API không?
• Sự hoàn chỉnh. Mọi thao tác mới đều cần một summary, các schema phản hồi và các phản hồi lỗi.
• Ví dụ. Các ví dụ thực tế làm cho tài liệu và bản mock trở nên hữu ích.

Để phát hiện các thay đổi gây phá vỡ, hãy dựa vào công cụ hơn là mắt thường. Một bước CI (được đề cập bên dưới) có thể so sánh đặc tả của PR với main và làm thất bại bản dựng nếu nó phát hiện ra một thay đổi không tương thích. Con người có thể bỏ sót những điều này; công cụ diff thì không.

Commit & push từ Apidog

Việc chỉnh sửa YAML thô bằng tay vẫn hoạt động, nhưng một trình chỉnh sửa trực quan với tính năng xác thực trực tiếp sẽ nhanh hơn và phát hiện lỗi sớm hơn. Chế độ Spec-First của Apidog cung cấp cho bạn tính năng đồng bộ hóa Git hai chiều: chỉnh sửa đặc tả trong giao diện người dùng, commit và đẩy lên kho lưu trữ của bạn mà không cần rời khỏi công cụ. Kéo các thay đổi của đồng đội về theo cùng một cách.

Quy trình trông như sau:

1. Kết nối kho Git của bạn và trỏ Apidog đến tệp đặc tả.
2. Chỉnh sửa các endpoint, schema và ví dụ trong trình chỉnh sửa trực quan.
3. Apidog ghi lại YAML sạch, thân thiện với diff vào tệp.
4. Commit trên một nhánh và đẩy, sau đó mở PR của bạn như bình thường.

Vì Apidog tuần tự hóa YAML một cách nhất quán, các bản diff của bạn sẽ nhỏ và dễ xem xét, không có sự sắp xếp lại hay định dạng lại gây nhiễu. Bạn có thể đọc hướng dẫn thiết lập đầy đủ trong tài liệu Chế độ Spec-First của Apidog. Nếu bạn muốn tệp được đưa vào một nhà cung cấp cụ thể, hãy xem đồng bộ hóa đặc tả OpenAPI của bạn với GitHub.

Các hook xác thực CI

Không bao giờ để một đặc tả không hợp lệ đến được nhánh main. Tích hợp xác thực vào các kiểm tra pull request của bạn để một hợp đồng bị hỏng sẽ tự động làm thất bại bản dựng.

Một bước GitHub Actions tối thiểu:

name: Validate OpenAPI
on: [pull_request]
jobs:
 lint:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - name: Lint spec
 run: npx @redocly/cli lint api/openapi.yaml

Thêm các kiểm tra khác khi bạn phát triển:

• Lint đặc tả để tìm các vấn đề về cấu trúc và kiểu dáng.
• Xác thực rằng nó được phân tích cú pháp thành OpenAPI 3.x hợp lệ.
• So sánh với main để phát hiện các thay đổi gây phá vỡ và gắn cờ chúng trên PR.

Các kiểm tra này chạy trong vài giây và bắt được những lỗi mà người đánh giá có thể bỏ qua.

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

Một vài thói quen giúp kiểm soát phiên bản đặc tả hoạt động tốt theo thời gian:

• Sử dụng phiên bản ngữ nghĩa (semantic versioning). Tăng trường info.version. Thay đổi gây phá vỡ có nghĩa là một phiên bản chính mới; các bổ sung tương thích ngược sẽ tăng phiên bản phụ.
• Duy trì nhật ký thay đổi (changelog). Một tệp CHANGELOG.md ngắn gọn bên cạnh đặc tả sẽ cho người dùng biết những gì đã thay đổi giữa các phiên bản.
• Gửi các bản diff nhỏ. Mỗi PR chỉ nên có một thay đổi logic. Các PR đặc tả lớn sẽ che giấu các thay đổi gây phá vỡ trong sự hỗn loạn.
• Viết các thông báo commit mô tả. "Thêm refundReason vào yêu cầu hoàn tiền" tốt hơn "cập nhật đặc tả."
• Không bao giờ chỉnh sửa trực tiếp đặc tả đã hợp nhất trên main. Luôn tạo nhánh, ngay cả khi chỉ là sửa lỗi chính tả.

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

Làm thế nào để phát hiện các thay đổi gây phá vỡ trong đặc tả OpenAPI?

Chạy một công cụ so sánh đặc tả (spec-diff tool) trong CI để so sánh pull request với phiên bản trên main. Các công cụ như oasdiff phân loại mỗi thay đổi là gây phá vỡ, không gây phá vỡ hoặc không phân loại, và có thể làm thất bại bản dựng nếu phát hiện thay đổi gây phá vỡ. Điều này giúp bắt được các trường bị xóa, tham số bắt buộc mới và các kiểu dữ liệu đã thay đổi mà việc xem xét thủ công có thể bỏ sót.

Tôi nên giữ một tệp OpenAPI hay chia nó thành nhiều tệp?

Hãy bắt đầu với một tệp openapi.yaml duy nhất. Đây là cách dễ nhất để xem xét và quản lý phiên bản. Khi tệp trở nên lớn hoặc bạn duy trì nhiều phiên bản chính song song, hãy chia theo phiên bản chính (api-v1.yaml, api-v2.yaml) hoặc sử dụng $ref để tách các schema thành các tệp riêng biệt. Đừng chia nhỏ quá sớm; một tệp dễ đọc tốt hơn năm tệp bị phân mảnh.

Tôi có thể kiểm soát phiên bản đặc tả của mình 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 sửa đặc tả trong trình chỉnh sửa trực quan và đồng bộ hóa các thay đổi với Git theo cả hai hướng. Nó ghi YAML nhất quán, vì vậy các bản diff của bạn vẫn sạch sẽ và các pull request của bạn vẫn dễ đọc, trong khi bạn vẫn nhận được đầy đủ lịch sử Git và khả năng xem xét.