Mã của bạn nằm trong Git. Các pipeline CI, đánh giá và lịch sử phát hành của bạn cũng nằm trong Git. Vậy tại sao đặc tả API của bạn lại nằm ở một nơi khác?
Quy trình làm việc API bản địa Git (Git-native API workflow) giữ định nghĩa OpenAPI của bạn ở cùng một nơi với mã của bạn. Bạn chỉnh sửa đặc tả dưới dạng một tệp YAML hoặc JSON thuần túy, commit nó và đẩy nó qua cùng một quy trình đánh giá mà bạn sử dụng cho mọi thứ khác. Không có cơ sở dữ liệu đám mây riêng biệt. Không có thao tác xuất-nhập phức tạp. Đặc tả chỉ là một tệp khác trong kho lưu trữ của bạn.
Ý nghĩa của quy trình làm việc API bản địa Git
Quy trình làm việc API bản địa Git coi đặc tả API của bạn như mã nguồn. Tệp OpenAPI nằm trong kho lưu trữ cùng với các dịch vụ của bạn. Mỗi thay đổi là một commit. Mỗi commit đều có người tạo, thông báo và sự khác biệt (diff).
Điều này mang lại cho bạn ba điều mà bạn mong đợi từ mã nguồn:
- Lịch sử phiên bản. Bạn có thể thấy ai đã thay đổi một endpoint và khi nào.
git blamehoạt động trên đặc tả của bạn. - Phân nhánh và đánh giá. Các thay đổi đặc tả trải qua các pull request. Người đánh giá thấy sự khác biệt chính xác trước khi bất kỳ điều gì được hợp nhất.
- Một nguồn chân lý duy nhất. Tệp trong nhánh
mainlà hợp đồng. Các công cụ, tài liệu và mock đều đọc từ đó.
Đây là ý tưởng cốt lõi đằng sau quy trình làm việc API ưu tiên đặc tả: đặc tả dẫn đầu, và việc triển khai theo sau. Để tìm hiểu sâu hơn về thực tiễn đó, hãy xem hướng dẫn của chúng tôi về phát triển API ưu tiên đặc tả.
Cách tiếp cận ngược lại là lưu trữ đặc tả của bạn trong một ứng dụng đám mây độc quyền. Điều đó hoạt động cho đến khi nhóm của bạn phát triển hoặc quy trình của bạn trở nên trưởng thành hơn. Sau đó, những vấn đề bắt đầu lộ rõ.
Vấn đề với các đặc tả API bị khóa trên đám mây
Hầu hết các công cụ thiết kế API đều giữ đặc tả trong cơ sở dữ liệu riêng của họ. Bạn chỉnh sửa thông qua giao diện người dùng của họ. "Tệp" mà bạn nghĩ là của mình thực ra chỉ là một hàng trong hệ thống của người khác.
Điều này gây ra sự cố theo những cách dễ đoán.
Việc đánh giá diễn ra ở hai nơi. Các thay đổi mã nguồn thông qua GitHub. Các thay đổi đặc tả thông qua một công cụ riêng biệt với các bình luận và lịch sử riêng. Người đánh giá phải chuyển đổi ngữ cảnh. Các phê duyệt trở nên không đồng bộ.
Sự khác biệt (diff) bị ẩn. Khi đặc tả nằm trong một cơ sở dữ liệu đám mây, bạn không thể thấy sự khác biệt từng dòng rõ ràng trong pull request của mình. Bạn phê duyệt một "thiết kế phiên bản 3" mà không biết thực sự có gì thay đổi.
Xuất khẩu trở thành một công việc nặng nhọc. Để đưa đặc tả vào CI, bạn xuất nó, commit tệp đã xuất và hy vọng không ai đã chỉnh sửa bản sao trên đám mây trong thời gian đó. Hai nguồn chân lý, một xung đột không thể tránh khỏi.
Tự động hóa chống lại bạn. Linters, kiểm thử hợp đồng và trình tạo mã đều muốn một tệp trên đĩa. Một đặc tả bị khóa trên đám mây buộc phải có một bước tìm nạp trước khi bất kỳ điều đó chạy.
Việc coi đặc tả API của bạn như mã nguồn sẽ loại bỏ tất cả những vấn đề này. Tệp là đặc tả. Git là lịch sử. Pipeline hiện có của bạn sẽ làm phần còn lại. Chúng tôi trình bày chi tiết nguyên tắc này trong bài viết Đặc tả API như mã nguồn.
Chế độ ưu tiên đặc tả của Apidog hoạt động như thế nào
Chế độ ưu tiên đặc tả được xây dựng cho các nhóm đã quen suy nghĩ bằng các commit và nhánh. Bạn thiết kế API dưới dạng tệp YAML hoặc JSON thô, và Apidog giữ các tệp đó đồng bộ hai chiều với kho lưu trữ Git của bạn.
Đây là những gì bạn nhận được.
Trình chỉnh sửa OpenAPI kiểu IDE
Bạn viết đặc tả trong một trình chỉnh sửa mã, không phải một biểu mẫu. Trình chỉnh sửa mang lại những tiện ích mà bạn mong đợi từ một IDE:
- Tô sáng cú pháp cho YAML và JSON.
- Xác thực theo lược đồ OpenAPI và Swagger, để lỗi hiển thị ngay khi bạn gõ.
- Tự động hoàn thành cho các từ khóa, kiểu dữ liệu và tham chiếu OpenAPI.
Bạn vẫn kiểm soát chính xác tệp. Không có trường ẩn, không có siêu dữ liệu chỉ dành cho giao diện người dùng.
Các tệp YAML/JSON thô
Đặc tả là một tệp thực. Một đoạn nhỏ của nó:
openapi: 3.1.0
info:
title: Orders API
version: 1.2.0
paths:
/orders/{orderId}:
get:
summary: Get an order by ID
operationId: getOrder
parameters:
- name: orderId
in: path
required: true
schema:
type: string
responses:
"200":
description: Order found
content:
application/json:
schema:
$ref: "#/components/schemas/Order"
"404":
description: Order not found
components:
schemas:
Order:
type: object
properties:
id:
type: string
status:
type: string
enum: [pending, shipped, delivered]
Đây là tệp sẽ nằm trong kho lưu trữ của bạn. Những gì bạn chỉnh sửa là những gì được commit.
Dàn ý tự động phân tích và điều hướng được
Khi bạn gõ, Apidog phân tích tệp và xây dựng một dàn ý trực quan ở thanh bên trái. Các đường dẫn, thao tác và lược đồ xuất hiện dưới dạng một cây mà bạn có thể nhấp để điều hướng. Bạn có được khả năng đọc của một công cụ thiết kế và độ chính xác của các tệp thô cùng một lúc.
Các đặc tả dài vẫn có thể điều hướng được. Chuyển đến một endpoint mà không cần cuộn qua hàng trăm dòng.
Đồng bộ Git hai chiều
Chế độ ưu tiên đặc tả kết nối với nhà cung cấp Git của bạn và đồng bộ hóa các thay đổi theo cả hai hướng. Nó hỗ trợ trực tiếp GitHub và GitLab, và Azure DevOps thông qua Git Connection.
Kéo các thay đổi mà đồng đội của bạn đã đẩy. Chỉnh sửa cục bộ trong trình soạn thảo Apidog. Sau đó commit và đẩy trở lại cùng một nhánh. Kho lưu trữ và không gian làm việc của bạn luôn được đồng bộ.
Commit, push và chỉ báo trạng thái đồng bộ
Bạn không cần rời khỏi Apidog để quản lý Git. Đưa các thay đổi của bạn vào khu vực staging, viết thông báo commit và đẩy. Một chỉ báo trạng thái đồng bộ cho bạn biết tình trạng hiện tại. Sau khi đẩy thành công, nó sẽ hiển thị "Đã đồng bộ ngay bây giờ." Nếu bạn thay đổi ý định trước khi đẩy, bạn có thể loại bỏ các chỉnh sửa chưa đẩy và trở về trạng thái đồng bộ cuối cùng.
Đồng bộ hóa hai chiều này là trọng tâm của quy trình làm việc API bản địa Git. Để có hướng dẫn chi tiết về phía GitHub, hãy xem đồng bộ hóa đặc tả OpenAPI với GitHub.
Hướng dẫn thiết lập
Đây là cách để đi từ một kho lưu trữ trống đến một đặc tả đã đồng bộ. Tài liệu tham khảo đầy đủ có trong tài liệu Chế độ ưu tiên đặc tả.
- Tạo một dự án từ một kho lưu trữ. Trong Apidog, bắt đầu một dự án Chế độ ưu tiên đặc tả mới và kết nối nhà cung cấp Git của bạn. Chọn kho lưu trữ chứa đặc tả API của bạn và chọn nhánh để theo dõi, thường là
main. Apidog kéo các tệp đặc tả hiện có vào trình chỉnh sửa.
- Chỉnh sửa đặc tả. Mở tệp OpenAPI trong trình chỉnh sửa. Thêm một endpoint, điều chỉnh lược đồ, hoặc sửa một phản hồi. Tô sáng cú pháp, xác thực và tự động hoàn thành sẽ hướng dẫn bạn khi bạn viết. Dàn ý thanh bên trái cập nhật khi tệp thay đổi.
- Theo dõi các tệp đã sửa đổi, thêm và xóa. Apidog hiển thị những tệp bạn đã thay đổi kể từ lần đồng bộ cuối cùng. Các tệp đã sửa đổi, thêm và xóa được đánh dấu để bạn biết chính xác những gì sắp được commit.
- Viết thông báo commit. Mô tả thay đổi bằng ngôn ngữ đơn giản, giống như bạn làm trong bất kỳ ứng dụng Git client nào. "Thêm phản hồi 404 cho getOrder" tốt hơn "cập nhật đặc tả."
- Đẩy (Push). Gửi commit đến nhánh được theo dõi. Đồng đội và pipeline CI của bạn giờ đây sẽ thấy phiên bản mới.
- Kiểm tra "Đã đồng bộ ngay bây giờ." Quan sát chỉ báo trạng thái đồng bộ xác nhận việc đẩy. Khi nó hiển thị "Đã đồng bộ ngay bây giờ", các chỉnh sửa cục bộ của bạn và nhánh từ xa đã khớp. Từ đây, thay đổi sẽ chảy qua quy trình pull request và đánh giá thông thường của bạn.
Đó là vòng lặp hoàn chỉnh: kéo, chỉnh sửa, commit, đẩy, xác minh. Không có bước xuất. Không có nguồn chân lý thứ hai.
Chế độ ưu tiên đặc tả so với chế độ ưu tiên thiết kế
Apidog hỗ trợ hai cách làm việc. Sự khác biệt nằm ở nơi đặc tả được lưu trữ và cách bạn chỉnh sửa nó.
| Chế độ ưu tiên đặc tả (beta) | Chế độ ưu tiên thiết kế | |
|---|---|---|
| Lưu trữ đặc tả | Các tệp YAML/JSON thô trong Git | Dự án đám mây Apidog |
| Trình chỉnh sửa chính | Trình chỉnh sửa mã kiểu IDE | Giao diện người dùng trực quan dựa trên biểu mẫu |
| Kiểm soát phiên bản | Git gốc (commits, nhánh, diffs) | Lịch sử và nhánh của Apidog |
| Đồng bộ Git hai chiều | Có (GitHub, GitLab, Azure DevOps) | Thông qua xuất/nhập |
| Phù hợp nhất cho | Các nhóm làm việc nhiều với Git | Các nhóm thích quy trình làm việc trực quan |
Không có chế độ nào "tốt hơn". Chúng phục vụ các thói quen khác nhau. Nếu quy trình đánh giá và phát hành của bạn đã chạy trên Git, Chế độ ưu tiên đặc tả sẽ loại bỏ sự phức tạp. Nếu nhóm của bạn thiết kế trực quan và hiếm khi chạm vào OpenAPI thô, Chế độ ưu tiên thiết kế có thể phù hợp hơn.
Khi nào nên sử dụng
Hãy chọn Chế độ ưu tiên đặc tả khi:
- Đặc tả của bạn nên trải qua các pull request và đánh giá mã.
- Bạn muốn
git blamevà lịch sử commit thực sự trên hợp đồng API của mình. - CI của bạn chạy kiểm tra lỗi đặc tả (spec linting), kiểm thử hợp đồng hoặc tạo mã cần một tệp trên đĩa.
- Nhiều kỹ sư chỉnh sửa đặc tả và bạn muốn các diff rõ ràng, có thể hợp nhất.
- Bạn đã chán ngấy việc xuất từ công cụ này để đưa vào công cụ khác.
Hãy gắn bó với cách tiếp cận trực quan, ưu tiên đám mây khi nhóm của bạn thiết kế API mà không cần viết OpenAPI thô, hoặc khi những người không phải kỹ sư sở hữu đặc tả và ưa thích một trình chỉnh sửa dựa trên biểu mẫu.
Câu hỏi thường gặp
Quy trình làm việc API bản địa Git là gì?
Quy trình làm việc API bản địa Git lưu trữ đặc tả OpenAPI của bạn dưới dạng một tệp trong kho lưu trữ Git và quản lý mọi thay đổi thông qua các commit, nhánh và pull request. Đặc tả tuân theo cùng một quy trình đánh giá và kiểm soát phiên bản như mã ứng dụng của bạn, do đó chỉ có một nguồn chân lý duy nhất.
Chế độ ưu tiên đặc tả của Apidog có hỗ trợ GitHub và GitLab không?
Có. Chế độ ưu tiên đặc tả đồng bộ hóa hai chiều trực tiếp với GitHub và GitLab. Azure DevOps được hỗ trợ thông qua Git Connection. Bạn kết nối kho lưu trữ, chọn một nhánh, và Apidog giữ các chỉnh sửa của bạn và kho lưu trữ từ xa luôn đồng bộ.
Tôi có thể chỉnh sửa các tệp OpenAPI dưới dạng YAML hoặc JSON thô không?
Có. Chế độ ưu tiên đặc tả cung cấp cho bạn một trình chỉnh sửa kiểu IDE cho các tệp YAML và JSON thô, với tính năng tô sáng cú pháp, xác thực lược đồ và tự động hoàn thành cho OpenAPI và Swagger. Một dàn ý thanh bên trái tự động phân tích tệp để bạn có thể điều hướng các đặc tả lớn một cách nhanh chóng.
Sự khác biệt giữa chế độ ưu tiên đặc tả và chế độ ưu tiên thiết kế là gì?
Chế độ ưu tiên đặc tả giữ đặc tả của bạn dưới dạng tệp trong Git và chỉnh sửa chúng trong trình chỉnh sửa mã với đồng bộ hóa hai chiều. Chế độ ưu tiên thiết kế giữ đặc tả trong một dự án đám mây Apidog với một trình chỉnh sửa trực quan, dựa trên biểu mẫu. Chọn Chế độ ưu tiên đặc tả nếu quy trình làm việc của bạn đã chạy trên Git.
Kết luận
Quy trình làm việc API bản địa Git chấm dứt sự chia rẽ giữa mã của bạn và hợp đồng API của bạn. Đặc tả trở thành một tệp, tệp trở thành một commit, và commit chảy qua quy trình đánh giá mà bạn đã tin tưởng.
Chế độ ưu tiên đặc tả của Apidog cung cấp cho bạn trình chỉnh sửa kiểu IDE, dàn ý có thể điều hướng và đồng bộ Git hai chiều để biến điều đó thành hiện thực. Bạn chỉnh sửa YAML hoặc JSON thô, commit một thông báo rõ ràng, đẩy và xem trạng thái hiển thị "Đã đồng bộ ngay bây giờ."
Hãy thử Chế độ ưu tiên đặc tả và đưa đặc tả API của bạn về với Git.