Chế độ Spec-first (Beta)

Chế độ Spec-first dành cho các nhóm muốn các tệp đặc tả API là nguồn chân lý. Trong chế độ này, bạn thiết kế và duy trì trực tiếp các tệp OpenAPI hoặc Swagger trong Apidog, xem trước tài liệu API được tạo trong khi chỉnh sửa, đồng thời giữ các tệp được đồng bộ hóa với Git.

Sử dụng Chế độ Spec-first khi nhóm của bạn đã làm việc với các tệp đặc tả YAML hoặc JSON, rà soát các thay đổi API thông qua Git, hoặc muốn việc thiết kế API phù hợp một cách tự nhiên với quy trình làm việc của kho mã nguồn.

Cách Chế độ Spec-first Hoạt động

Trong một dự án Apidog thông thường, API thường được tạo và chỉnh sửa thông qua các biểu mẫu trực quan. Trong một dự án Spec-first, không gian làm việc chính dựa trên tệp.

Bạn làm việc với các tệp như:

openapi.yaml

openapi.json

Các tệp Swagger 2.0

Các tệp Markdown và các tệp dự án hỗ trợ khác

Apidog phân tích cú pháp các tệp đặc tả và chuyển chúng thành một cấu trúc API có thể điều hướng. Bạn có thể chỉnh sửa các tệp thô, sử dụng các biểu mẫu trực quan được hỗ trợ, xác thực đặc tả, xem trước tài liệu được tạo và đẩy các thay đổi trở lại Git.

Tạo Dự án Spec-first

Nhấp vào + New Project.

Trong bộ chọn loại dự án, chọn Spec-first Mode.

Kết nối một nhà cung cấp Git, chẳng hạn như GitHub, GitLab, Azure DevOps hoặc Bitbucket.

Chọn một tổ chức hoặc workspace, sau đó chọn một repository hiện có hoặc tạo một repository mới nếu tùy chọn này khả dụng.

Chọn nhánh chính mà Apidog nên đồng bộ hóa.

Chọn có cài đặt webhook hay không.

Việc cài đặt webhook cho phép các lần push trong Git repository kích hoạt đồng bộ hóa tự động. Thao tác này thường yêu cầu quyền quản trị trên repository. Nếu bạn không có quyền quản trị, bạn có thể bỏ qua việc cài đặt webhook và đồng bộ hóa thủ công.

Nhập tên dự án, cấu hình quyền của thành viên và nhấp vào Create.

Sau khi tạo, Apidog thực hiện lần đồng bộ hóa đầu tiên. Nếu nhánh mặc định của repository không phải là main, Apidog sử dụng tên nhánh của repository làm nhánh chính của dự án.

Các dự án Spec-first không bao gồm dữ liệu dự án mẫu. Nội dung API đến từ các tệp đặc tả của bạn.

Workspace Specs

Các dự án Spec-first bao gồm một workspace Specs trong thanh bên trái. Đây là nơi chính để quản lý các tệp đặc tả và đồng bộ hóa Git.

Workspace này chứa ba khu vực chính:

Trình khám phá tệp: Duyệt và quản lý các tệp và thư mục từ repository đã đồng bộ hóa.

Cây cấu trúc API: Điều hướng nội dung OpenAPI đã được phân tích cú pháp, chẳng hạn như tổng quan, endpoint, schema và định nghĩa.

Trình chỉnh sửa: Chỉnh sửa tệp trong chế độ xem mã hoặc, đối với các nút OpenAPI được hỗ trợ, trong chế độ xem biểu mẫu.

Khi bạn chọn một endpoint, schema hoặc nút được hỗ trợ khác trong cây cấu trúc, Apidog mở phần liên quan của tệp nguồn. Điều này cho phép bạn di chuyển giữa chế độ xem cấp tệp và chế độ xem cấp API mà không cần rời khỏi workspace Specs.

Chỉnh sửa Tệp Đặc tả

Trình chỉnh sửa hỗ trợ nhiều loại tệp và chế độ chỉnh sửa khác nhau.

Chế độ xem Code

Sử dụng chế độ xem Code để chỉnh sửa trực tiếp YAML, JSON, Markdown và các tệp văn bản khác. Đây là cách làm việc mặc định trong Chế độ Spec-first.

Chế độ xem Form

Đối với các nút OpenAPI được hỗ trợ, Apidog cũng cung cấp chế độ xem Form. Chế độ này cho phép bạn chỉnh sửa các trường API phổ biến thông qua các điều khiển có cấu trúc, đồng thời vẫn giữ tệp đặc tả bên dưới làm nguồn chân lý.

Chế độ xem Form khả dụng cho các nút được hỗ trợ như:

Tổng quan API

Endpoint

Schema

Định nghĩa

Nếu tệp hoặc nút đã chọn không thể được chỉnh sửa trong chế độ xem Form, Apidog giữ bạn ở chế độ xem Code.

Xác thực và Xem trước Trong khi Chỉnh sửa

Chế độ Spec-first bao gồm các công cụ xác thực và xem trước trong header của trình chỉnh sửa.

Xác thực

Bảng Validation hiển thị các vấn đề được phát hiện trong đặc tả hiện tại, bao gồm cảnh báo và lỗi. Huy hiệu xác thực hiển thị tổng số vấn đề đã phát hiện.

Sử dụng bảng này để tìm các vấn đề cú pháp, các trường bắt buộc bị thiếu và các vi phạm quy tắc trước khi commit thay đổi.

Xem trước

Bảng Preview hiển thị cách nút đặc tả đã chọn sẽ xuất hiện trong tài liệu API được tạo.

Preview khả dụng cho:

Tổng quan API

Endpoint

Schema

Định nghĩa

Đối với endpoint, Preview bao gồm:

Docs: Tài liệu endpoint được tạo.

Try it out: Một bảng yêu cầu để gửi yêu cầu dựa trên định nghĩa endpoint đã chọn.

Đối với schema, định nghĩa và các nút tổng quan, Preview hiển thị chế độ xem tài liệu được tạo.

Validation và Preview sử dụng cùng một bảng bên. Mở một bảng sẽ đóng bảng còn lại.

Đồng bộ hóa Thay đổi từ Git

Khi các thành viên khác trong nhóm push thay đổi lên repository đã kết nối, bạn có thể kéo các tệp mới nhất vào Apidog.

Mở workspace Specs.

Nhấp vào tên nhánh hiện tại trong thanh bên Specs.

Nhấp vào Git Pull.

Nếu đồng bộ hóa webhook đã được cài đặt, Apidog cũng có thể nhận các sự kiện push từ nhà cung cấp Git và tự động kích hoạt đồng bộ hóa.

Commit và Push Thay đổi lên Git

Sau khi chỉnh sửa tệp trong Apidog, hãy push các thay đổi của bạn trở lại repository đã kết nối.

Chỉnh sửa một hoặc nhiều tệp trong workspace Specs.

Nhấp vào Changes để rà soát các tệp đã sửa đổi, đã thêm, đã đổi tên và đã xóa.

Nhấp vào Commit & Push.

Trong modal Push to Git repo, chọn các tệp bạn muốn bao gồm.

Nhập thông điệp commit.

Nhấp vào Push.

Nếu bạn không muốn giữ các chỉnh sửa cục bộ, hãy sử dụng Discard all changes trước khi push.

Quản lý Nhánh

Chế độ Spec-first hỗ trợ cộng tác dựa trên nhánh. Apidog ánh xạ các nhánh Git đã đồng bộ hóa với các nhánh dự án để bạn có thể chuyển đổi giữa các phiên bản của đặc tả.

Chuyển Nhánh

Nhấp vào tên nhánh trong thanh bên Specs và chọn một nhánh khác từ menu thả xuống.

Theo dõi một Nhánh Git Hiện có

Nếu một nhánh tồn tại trong Git nhưng chưa được nhập vào Apidog, hãy nhấp vào Import New Branch, chọn nhánh và nhập nhánh đó. Sau đó, Apidog bắt đầu theo dõi và đồng bộ hóa nhánh đó.

Tạo một Nhánh

Mở Project Settings > Git & Branches và nhấp vào New Branch để tạo một nhánh từ một nhánh dự án hiện có.

Đồng bộ hóa lại một Nhánh

Nếu quá trình đồng bộ hóa nhánh thất bại hoặc các tệp có vẻ lỗi thời, hãy sử dụng Re-sync trong Project Settings > Git & Branches. Thao tác này đặt lại trạng thái đồng bộ hóa cho nhánh đó và nhập lại các tệp.

Xem Nhật ký Đồng bộ hóa

Nếu quá trình đồng bộ hóa thất bại, hãy mở các hành động của nhánh và chọn View Logs để kiểm tra chi tiết đồng bộ hóa.

Ngừng Theo dõi hoặc Xóa một Nhánh

Việc xóa một nhánh được theo dõi sẽ loại bỏ nhánh đó khỏi cấu hình đồng bộ hóa của Apidog. Đối với các nhánh không phải nhánh chính, bản ghi nhánh dự án cũng có thể bị xóa.

Đồng bộ hóa Webhook và Quyền

Đồng bộ hóa webhook là tùy chọn nhưng được khuyến nghị cho các nhóm muốn Apidog luôn cập nhật với các lần push repository.

Khi đồng bộ hóa webhook được bật:

Apidog đăng ký một webhook trên nhà cung cấp Git đã kết nối.

Chỉ các sự kiện push được hỗ trợ mới được xử lý.

Apidog xác minh chữ ký hoặc token webhook trước khi đồng bộ hóa.

Yêu cầu về quyền:

Việc cài đặt webhook thường yêu cầu quyền quản trị repository.

Việc push thay đổi yêu cầu quyền ghi.

Nếu bỏ qua việc cài đặt webhook, đồng bộ hóa thủ công vẫn khả dụng.

Nếu bạn đã bỏ qua việc cài đặt webhook trong quá trình tạo dự án, bạn có thể cài đặt sau từ Project Settings > Git & Branches.

Dự án Spec-first Dựa trên Lưu trữ

Một số dự án Spec-first có thể sử dụng bộ nhớ nội bộ của Apidog thay vì một Git repository bên ngoài.

Các dự án này vẫn sử dụng workspace Specs, chỉnh sửa dựa trên tệp, xác thực, xem trước và quản lý nhánh.

Nhãn UI hơi khác:

Git Pull xuất hiện dưới dạng Sync.

Commit & Push xuất hiện dưới dạng Save.

Thông tin nhà cung cấp Git và cài đặt webhook bên ngoài được ẩn.

Ghi chú và Giới hạn

Chế độ Spec-first hiện đang ở bản beta.

Workspace Specs chỉ xuất hiện trong các dự án Spec-first.

Các dự án Spec-first không tạo dữ liệu API mẫu.

Tệp đặc tả là nguồn chân lý. Các thay đổi nên được thực hiện thông qua workspace Specs hoặc được đồng bộ hóa thông qua Git.

Việc cài đặt webhook có thể thất bại nếu bạn không có đủ quyền repository. Bạn vẫn có thể sử dụng đồng bộ hóa thủ công nếu có quyền ghi.

Chế độ Spec-first (Beta)

Cách Chế độ Spec-first Hoạt động#

Tạo Dự án Spec-first#

Workspace Specs#

Chỉnh sửa Tệp Đặc tả#

Chế độ xem Code#

Chế độ xem Form#

Xác thực và Xem trước Trong khi Chỉnh sửa#

Xác thực#

Xem trước#

Đồng bộ hóa Thay đổi từ Git#

Commit và Push Thay đổi lên Git#

Quản lý Nhánh#

Chuyển Nhánh#

Theo dõi một Nhánh Git Hiện có#

Tạo một Nhánh#

Đồng bộ hóa lại một Nhánh#

Xem Nhật ký Đồng bộ hóa#

Ngừng Theo dõi hoặc Xóa một Nhánh#

Đồng bộ hóa Webhook và Quyền#

Dự án Spec-first Dựa trên Lưu trữ#

Ghi chú và Giới hạn#