Thông số kỹ thuật OpenAPI của bạn là hợp đồng giữa API và người tiêu dùng của nó. Nhưng hợp đồng đó nằm ở đâu?
Quá thường xuyên, các thông số kỹ thuật API nằm trong các công cụ biệt lập—chỉ được xuất một lần, bị lãng quên và hiếm khi được cập nhật khi triển khai thay đổi. Tài liệu không đồng bộ. Các bộ sưu tập thử nghiệm phân kỳ. Người đánh giá chấp thuận các thay đổi mã mà không bao giờ thấy các cập nhật thông số tương ứng.
Chế độ ưu tiên Spec (Spec-first Mode) thay đổi mô hình này. Các tệp OpenAPI hoặc Swagger của bạn trở thành nguồn chân lý, được lưu trữ trực tiếp trong kho lưu trữ Git cùng với mã triển khai. Mọi thay đổi thông số đều trải qua cùng các nhánh, yêu cầu kéo và quy trình xem xét mà bạn đã sử dụng. Thiết kế API, thử nghiệm và tài liệu đều được đồng bộ hóa—tự động.
Trong hướng dẫn này, tôi sẽ hướng dẫn bạn thiết lập một dự án ưu tiên Spec trong Apidog, chỉnh sửa các thông số kỹ thuật với nhóm của bạn và giữ mọi thứ đồng bộ với quy trình làm việc Git của bạn.
Chế độ ưu tiên Spec là gì?
Trong một dự án API điển hình, bạn tạo các điểm cuối thông qua các biểu mẫu trực quan hoặc nhập các thông số kỹ thuật hiện có làm điểm khởi đầu. Công cụ này lưu trữ các định nghĩa API nội bộ và tích hợp Git (nếu có) là một bước xuất.
Chế độ ưu tiên Spec khác biệt. Không gian làm việc chính dựa trên tệp:
openapi.yamlhoặcopenapi.jsonnằm trong kho lưu trữ của bạn- Apidog phân tích cú pháp các tệp này và tạo cấu trúc API có thể điều hướng
- Bạn chỉnh sửa các tệp trực tiếp (hoặc thông qua các biểu mẫu được hỗ trợ)
- Các thay đổi tự động đồng bộ trở lại Git
Tệp thông số kỹ thuật luôn có thẩm quyền. Apidog đọc từ đó, ghi vào đó và giữ nó đồng bộ với kho lưu trữ của bạn.
Điều kiện tiên quyết
Để làm theo, bạn sẽ cần:
- Một tài khoản Apidog (gói miễn phí cũng được)
- Một kho lưu trữ Git với tệp OpenAPI/Swagger, hoặc một kho lưu trữ trống để bắt đầu mới
- Quyền ghi vào kho lưu trữ
- Hiểu biết cơ bản về cú pháp OpenAPI hoặc Swagger
Bước 1: Tạo một dự án ưu tiên Spec
Nhấp vào + Dự án Mới trong Apidog và chọn Chế độ ưu tiên Spec làm loại dự án.
Tiếp theo, kết nối nhà cung cấp Git của bạn:
- Chọn nhà cung cấp của bạn (GitHub, GitLab, Azure DevOps hoặc Bitbucket)
- Chọn một tổ chức hoặc không gian làm việc
- Chọn một kho lưu trữ hiện có hoặc tạo một kho lưu trữ mới
- Chọn nhánh chính để đồng bộ hóa
Apidog sẽ đồng bộ hóa với nhánh mặc định của kho lưu trữ của bạn. Nếu nó không được đặt tên là main, Apidog sẽ tự động điều chỉnh.
Bước 2: Cấu hình đồng bộ hóa Webhook (Khuyến nghị)
Trong quá trình thiết lập, bạn sẽ thấy tùy chọn cài đặt webhook. Điều này cho phép đồng bộ hóa tự động bất cứ khi nào nhóm của bạn đẩy lên kho lưu trữ.
Lưu ý: Cài đặt Webhook thường yêu cầu quyền quản trị trên kho lưu trữ. Nếu bạn không có quyền quản trị, hãy bỏ qua bước này—bạn vẫn có thể đồng bộ hóa thủ công bằng cách sử dụng Git Pull.
Lợi ích của Webhook:
- Nhóm đẩy các thay đổi → Apidog tự động đồng bộ hóa
- Không cần làm mới thủ công
- Mọi người đều thấy trạng thái thông số mới nhất
Nếu bạn đã bỏ qua thiết lập webhook ban đầu, bạn có thể thêm nó sau từ Cài đặt Dự án > Git & Nhánh.
Bước 3: Khám phá không gian làm việc Specs
Sau khi tạo, dự án của bạn mở không gian làm việc Specs—trung tâm cho chỉnh sửa dựa trên tệp và các hoạt động Git.
Ba bảng điều khiển hoạt động cùng nhau:
| Bảng điều khiển | Nội dung hiển thị |
|---|---|
| Trình duyệt Tệp | Tất cả các tệp và thư mục từ kho lưu trữ đã đồng bộ hóa của bạn |
| Cây cấu trúc API | Nội dung OpenAPI đã phân tích: điểm cuối, lược đồ, định nghĩa, tổng quan |
| Trình chỉnh sửa | Chỉnh sửa tệp trong chế độ xem mã hoặc chế độ xem biểu mẫu |
Nhấp vào một điểm cuối trong cây cấu trúc → Apidog làm nổi bật phần tương ứng trong tệp nguồn của bạn. Điều hướng từ chế độ xem API cấp cao đến YAML cấp thấp mà không cần chuyển tab.
Bước 4: Chỉnh sửa tệp thông số kỹ thuật của bạn
Chế độ xem mã: Chỉnh sửa trực tiếp
Đối với hầu hết các tệp—YAML, JSON, Markdown—sử dụng chế độ xem Mã để chỉnh sửa văn bản thô.
Các chỉnh sửa của bạn vẫn nằm trong tệp. Apidog không chuyển đổi hoặc lưu trữ chúng riêng. Tệp thông số vẫn là nguồn chân lý duy nhất.
Chế độ xem biểu mẫu: Chỉnh sửa có cấu trúc
Đối với các nút OpenAPI được hỗ trợ—điểm cuối, lược đồ, định nghĩa và tổng quan API—chuyển sang chế độ xem Biểu mẫu.
Chế độ xem biểu mẫu hữu ích khi:
- Thêm điểm cuối với tất cả các trường bắt buộc mà không cần ghi nhớ cấu trúc YAML
- Chỉnh sửa lược đồ trực quan
- Cập nhật định nghĩa bảo mật và siêu dữ liệu API
Nếu một nút không hỗ trợ chỉnh sửa biểu mẫu, Apidog sẽ giữ bạn ở chế độ xem mã.
Bước 5: Xác thực và xem trước ngay lập tức
Chế độ ưu tiên Spec bao gồm xác thực theo thời gian thực và xem trước tài liệu—không cần công cụ bên ngoài.
Kiểm tra các vấn đề với xác thực
Nhấp vào Xác thực trong tiêu đề trình chỉnh sửa. Một bảng điều khiển hiển thị tất cả các cảnh báo và lỗi trong thông số hiện tại của bạn.
Huy hiệu hiển thị tổng số vấn đề. Phát hiện:
- Lỗi cú pháp
- Thiếu các trường bắt buộc
- Vi phạm lược đồ
- Các vấn đề về quy ước đặt tên
Khắc phục các vấn đề trước khi cam kết. Người đánh giá của nhóm bạn sẽ không cần phải tự mình phát hiện ra những vấn đề này.
Xem trước tài liệu của bạn
Nhấp vào Xem trước để xem thông số của bạn hiển thị dưới dạng tài liệu API như thế nào.
Đối với điểm cuối, bản xem trước bao gồm hai tab:
| Tab | Nội dung |
|---|---|
| Tài liệu | Tài liệu điểm cuối đã tạo |
| Thử ngay | Bảng yêu cầu trực tiếp dựa trên định nghĩa điểm cuối |
Đối với lược đồ và định nghĩa, bản xem trước hiển thị chế độ xem tài liệu đã kết xuất.
Xác thực và Xem trước chia sẻ cùng một bảng điều khiển bên. Mở một cái sẽ tự động đóng cái còn lại.
Bước 6: Kéo các bản cập nhật từ nhóm của bạn
Khi các cộng tác viên đẩy các thay đổi lên kho lưu trữ của bạn, hãy đưa chúng vào Apidog:
- Mở không gian làm việc Specs
- Nhấp vào tên nhánh hiện tại trong thanh bên
- Chọn Git Pull
Nếu đồng bộ hóa webhook đang hoạt động, Apidog sẽ tự động kéo trên các sự kiện đẩy kho lưu trữ—không cần bước thủ công.
Bước 7: Cam kết và đẩy các thay đổi của bạn
Sau khi chỉnh sửa tệp trong Apidog, hãy gửi các cập nhật của bạn trở lại Git:
- Thực hiện các thay đổi trong không gian làm việc Specs
- Nhấp vào Thay đổi trong thanh bên để xem các tệp đã sửa đổi, thêm, đổi tên và xóa
- Nhấp vào Commit & Push
- Chọn tệp nào sẽ đưa vào
- Viết thông điệp cam kết
- Nhấp vào Push
Các cập nhật thông số kỹ thuật của bạn giờ đây xuất hiện trong cùng quy trình yêu cầu kéo với các thay đổi mã của bạn. Các đồng đội có thể xem xét, bình luận và phê duyệt—cả việc triển khai và hợp đồng API ở cùng một nơi.
Mẹo: Sử dụng Hủy bỏ tất cả các thay đổi nếu bạn muốn từ bỏ các chỉnh sửa cục bộ trước khi đẩy.
Bước 8: Làm việc với các nhánh
Chế độ ưu tiên Spec hỗ trợ cộng tác dựa trên nhánh đầy đủ. Apidog ánh xạ các nhánh Git tới các nhánh dự án, cho phép bạn chuyển đổi giữa các phiên bản thông số kỹ thuật.
Các thao tác nhánh phổ biến
| Thao tác | Cách thực hiện |
|---|---|
| Chuyển nhánh | Nhấp vào tên nhánh → chọn một nhánh khác |
| Nhập nhánh Git hiện có | Nhấp vào Nhập Nhánh Mới → chọn → nhập |
| Tạo nhánh mới | Cài đặt Dự án > Git & Nhánh → Nhánh Mới |
| Khắc phục sự cố đồng bộ hóa | Sử dụng Đồng bộ hóa lại trong cài đặt nhánh |
| Xem nhật ký đồng bộ hóa | Thao tác nhánh → Xem Nhật ký |
Quản lý nhánh hoạt động theo cách bạn mong đợi từ Git—các nhánh tính năng, bản phát hành và phát triển song song đều đồng bộ hóa chính xác.
Bước 9: Tích hợp với CI/CD
Vì thông số kỹ thuật của bạn nằm trong Git, chúng tự nhiên phù hợp với các đường ống tự động hóa:
- Kiểm tra cú pháp thông số kỹ thuật trên mỗi PR bằng cách sử dụng xác thực Apidog hoặc các công cụ như Spectral
- Tạo tài liệu tự động khi thông số kỹ thuật được hợp nhất vào nhánh chính
- Chạy kiểm thử API được kích hoạt bởi các thay đổi thông số kỹ thuật
- Đồng bộ hóa với các hệ thống hạ nguồn—cổng API, máy chủ giả lập, trình tạo SDK
Ví dụ quy trình GitHub Actions:
name: Validate and Test API Spec
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Lint OpenAPI Spec
run: npx spectral lint openapi.yaml
- name: Run API Tests
run: apidog run tests --spec openapi.yamlCác thông số kỹ thuật API của bạn giờ đây sẽ vượt qua các cổng chất lượng tương tự như mã ứng dụng của bạn.
Thay thế: Các dự án được hỗ trợ bởi lưu trữ
Nếu bạn chưa sẵn sàng kết nối một kho lưu trữ Git bên ngoài, Apidog cung cấp các dự án ưu tiên Spec được hỗ trợ bởi lưu trữ.
Các dự án này sử dụng bộ nhớ nội bộ của Apidog nhưng vẫn cung cấp:
- Chỉnh sửa dựa trên tệp
- Xác thực và xem trước
- Quản lý nhánh
Các nhãn giao diện người dùng điều chỉnh một chút:
- Git Pull trở thành Đồng bộ hóa
- Commit & Push trở thành Lưu
Di chuyển sang Git bên ngoài bất cứ khi nào nhóm của bạn sẵn sàng.
Tóm tắt
Với Chế độ ưu tiên Spec, quy trình làm việc API của bạn trở thành:
| Trước khi có ưu tiên Spec | Sau khi có ưu tiên Spec |
|---|---|
| Thông số kỹ thuật nằm trong một công cụ riêng biệt | Thông số kỹ thuật nằm trong kho lưu trữ Git của bạn |
| Xuất/nhập để đồng bộ hóa | Đồng bộ hóa tự động khi đẩy |
| Đánh giá diễn ra bên ngoài đánh giá mã | Đánh giá diễn ra trong các yêu cầu kéo |
| Tài liệu được tạo riêng | Xem trước trong khi chỉnh sửa |
| Kiểm thử bị ngắt kết nối với các thay đổi thông số kỹ thuật | Kiểm thử được kích hoạt bởi các cập nhật thông số kỹ thuật |
Chế độ ưu tiên Spec biến các tệp OpenAPI thành hợp đồng như chúng phải là—được tạo phiên bản, được xem xét và luôn đồng bộ với mã của bạn.
Sẵn sàng thử chưa? Tạo một dự án ưu tiên Spec trong Apidog và kết nối kho lưu trữ đầu tiên của bạn.