Nếu bạn đang chuyển từ Stoplight Studio hoặc Stoplight Platform sang Apidog, điều đầu tiên cần biết là bạn không cần phải tải lại các thông số kỹ thuật OpenAPI của mình. Chế độ Spec-First (hiện đang trong giai đoạn thử nghiệm) của Apidog kết nối trực tiếp với kho lưu trữ GitHub hoặc GitLab hiện có của bạn, do đó Git vẫn là nguồn thông tin chính xác và lịch sử commit của bạn vẫn nguyên vẹn. Hướng dẫn này sẽ hướng dẫn bạn từng bước: xuất cấu hình Stoplight của bạn, ánh xạ các quy ước thư mục của nó sang các yêu cầu của Apidog và thay thế .stoplight.json và toc.json bằng các tương đương của Apidog.
Các nhóm như tại Diễn đàn Kinh tế Thế giới đã quản lý các thông số kỹ thuật OpenAPI trong Git cùng với Stoplight để tạo tài liệu. Nếu đó là thiết lập của bạn, hướng dẫn này được viết cho bạn. Và nếu bạn vẫn đang cân nhắc các lựa chọn thay vì cam kết di chuyển, bài đăng các giải pháp thay thế Stoplight Studio tốt nhất sẽ bao gồm tổng quan rộng hơn.
Điều gì không thay đổi khi bạn di chuyển
Các tệp OpenAPI, kho lưu trữ Git và chiến lược nhánh của bạn không thay đổi. Đó là tiền đề chính. Stoplight lưu trữ các thông số kỹ thuật dưới dạng tệp YAML hoặc JSON được kiểm tra vào kiểm soát nguồn. Apidog đọc các tệp tương tự đó khi bạn kết nối một kho lưu trữ ở Chế độ Spec-First.
Điều thay đổi là mọi thứ được xếp lớp lên trên: trình kết xuất tài liệu, máy chủ mô phỏng, trình chạy thử nghiệm và máy khách API. Thay vì Stoplight Platform cung cấp tài liệu và Postman xử lý các thử nghiệm như một công cụ riêng biệt, Apidog kết hợp tất cả những điều đó trong một không gian làm việc, được đồng bộ hóa với cùng một tệp OpenAPI mà các kỹ sư của bạn đã cam kết.
Kết quả thực tế: quá trình di chuyển của bạn chủ yếu là trao đổi cấu hình, không phải di chuyển dữ liệu.
Bước 1: Xuất các tài nguyên dự án Stoplight của bạn
Trước khi chạm vào Apidog, hãy thu thập mọi thứ Stoplight đang giữ mà chưa có trong Git.
Nếu bạn sử dụng Stoplight Studio với backend Git:
Các thông số kỹ thuật OpenAPI, mô hình JSON Schema và tài liệu Markdown của bạn đã được commit. Chạy git pull để đảm bảo bản sao cục bộ của bạn được cập nhật. Stoplight tuân theo định dạng OpenAPI Specification và các tệp đặc tả đó hoạt động trong Apidog mà không cần chuyển đổi. Cấu trúc kho lưu trữ của bạn có thể trông như thế này:
your-api-repo/
.stoplight.json # Cấu hình dự án (cần thay thế)
reference/
petstore.yaml # (Các) thông số kỹ thuật OpenAPI của bạn
models/
error.json # Các mô hình JSON Schema được chia sẻ
docs/
introduction.md # Các trang hướng dẫn Markdown
authentication.md
toc.json # Thứ tự mục lục (cần thay thế)
assets/
images/
architecture.png
Nếu bạn sử dụng Stoplight Platform (được lưu trữ trên đám mây, không có backend Git):
Xuất các thông số kỹ thuật của bạn từ giao diện người dùng Stoplight: mở từng dự án API, vào "Export" và tải xuống OpenAPI YAML. Đối với tài liệu Markdown, sao chép chúng vào thư mục docs/ trong một kho lưu trữ Git mới. Stoplight không cung cấp tính năng xuất hàng loạt cho các dự án không phải Git, vì vậy hãy thực hiện điều này cho từng dự án API.
Khi các tệp của bạn đã nằm trong một kho lưu trữ Git (GitHub hoặc GitLab), hãy tiếp tục bước tiếp theo.
Bước 2: Hiểu các tệp cấu hình bạn đang thay thế
Hai tệp dành riêng cho Stoplight điều khiển cấu trúc dự án. Cả hai đều không có đối tác trực tiếp trong Apidog, nhưng việc hiểu chức năng của chúng sẽ cho bạn biết chính xác những gì cần cấu hình trong Apidog thay thế.
| Tệp Stoplight | Chức năng | Tương đương Apidog |
|---|---|---|
.stoplight.json |
Khai báo thư mục gốc của dự án, đường dẫn thông số kỹ thuật, đường dẫn tài liệu và các tệp được bao gồm trong dự án | Cài đặt kết nối kho lưu trữ bên trong dự án Apidog (được cấu hình qua UI, không phải tệp) |
toc.json |
Kiểm soát thứ tự và nhóm các trang trong thanh bên tài liệu Stoplight | Apidog đọc cấu trúc thư mục; thứ tự thanh bên được đặt trong trình chỉnh sửa tài liệu Apidog, không phải tệp phẳng |
Quy ước reference/ |
Nơi Stoplight mong đợi các tệp thông số kỹ thuật OpenAPI | Có thể cấu hình trong Chế độ Spec-First của Apidog; mặc định là thư mục gốc của kho lưu trữ, nhưng bạn có thể trỏ nó đến reference/ |
Quy ước models/ |
Các tệp JSON Schema cho các thành phần được chia sẻ | Tham chiếu chúng từ phần components/schemas của thông số kỹ thuật OpenAPI của bạn; Apidog giải quyết các đường dẫn $ref |
Quy ước docs/ |
Các trang hướng dẫn Markdown | Nhập dưới dạng các trang tài liệu trong Apidog; hệ thống phân cấp thư mục ánh xạ tới các phần thanh bên |
Thông tin chính: .stoplight.json và toc.json là các tệp độc quyền của Stoplight. Bạn có thể để chúng trong kho lưu trữ (Apidog bỏ qua các tệp không xác định), nhưng chúng sẽ không điều khiển bất cứ điều gì trong Apidog. Bạn cấu hình các cài đặt tương đương thông qua giao diện người dùng dự án Apidog.
Bước 3: Kết nối kho lưu trữ của bạn với Chế độ Spec-First của Apidog
Chế độ Spec-First của Apidog là cách bạn liên kết một kho lưu trữ GitHub hoặc GitLab với một dự án Apidog để thông số kỹ thuật OpenAPI luôn được đọc từ Git, chứ không phải từ cơ sở dữ liệu nội bộ của Apidog. Điều này giữ Git làm nguồn đáng tin cậy và có nghĩa là các kỹ sư của bạn có thể tiếp tục gửi PR để cập nhật thông số kỹ thuật giống hệt như cách họ làm hiện tại.
Đây là luồng kết nối. Bạn cũng có thể xem lại tài liệu của GitHub về việc kết nối ứng dụng bên thứ ba với kho lưu trữ nếu bạn không chắc chắn về việc cấp quyền OAuth.
- Trong Apidog, tạo một dự án mới Spec-First Mode
- Xác thực Apidog với tài khoản GitHub hoặc GitLab của bạn và chọn kho lưu trữ.
3.Đặt nhánh: sử dụng nhánh mặc định của bạn (main hoặc master) cho các thông số kỹ thuật sản xuất, hoặc một nhánh tính năng trong quá trình kiểm tra di chuyển.
- Lưu. Apidog đọc thông số kỹ thuật và xây dựng tài liệu tương tác, các điểm cuối máy chủ mô phỏng và khung thử nghiệm từ đó.
Nếu thông số kỹ thuật của bạn sử dụng $ref để kéo các schema từ thư mục models/, Apidog sẽ giải quyết các tham chiếu đó tương đối với vị trí của tệp thông số kỹ thuật. Không cần cấu hình bổ sung miễn là các đường dẫn trong tệp OpenAPI của bạn chính xác. Để tìm hiểu sâu hơn về cách đồng bộ hóa Git này hoạt động, hướng dẫn đồng bộ hóa thông số kỹ thuật OpenAPI với GitHub trình bày chi tiết cơ chế này.
Bước 4: Di chuyển tài liệu Markdown của bạn
Stoplight cho phép bạn kết hợp các trang hướng dẫn Markdown với tài liệu tham khảo API trong một thanh bên duy nhất. Apidog cũng làm như vậy thông qua trình chỉnh sửa tài liệu của nó.
Sau khi kết nối kho lưu trữ của bạn, hãy nhập các tệp Markdown trong thư mục docs/ của bạn:
- Trong dự án Apidog, mở phần Docs.
- Sử dụng Import > Markdown và tải lên các tệp của bạn, hoặc dán nội dung từng trang.
Đối với các tài nguyên hình ảnh được tham chiếu trong Markdown của bạn (thư mục assets/images/ trong bố cục Stoplight điển hình), hãy tải chúng lên bộ lưu trữ tệp của Apidog và cập nhật các tham chiếu  trong mỗi trang. Nếu hình ảnh của bạn đã được lưu trữ trên CDN hoặc URL công khai, bạn không cần thay đổi gì.
Bước 5: Thay thế máy chủ mô phỏng của Stoplight
Stoplight Studio bao gồm một máy chủ mô phỏng cục bộ đọc thông số kỹ thuật OpenAPI của bạn và trả về các phản hồi ví dụ. Máy chủ mô phỏng của Apidog cũng làm như vậy, nhưng nó được lưu trữ trên đám mây và có thể truy cập được cho toàn bộ nhóm của bạn mà không cần chạy một quy trình cục bộ.
Khi thông số kỹ thuật của bạn được kết nối qua Chế độ Spec-First, Apidog tự động tạo các điểm cuối mô phỏng cho mọi thao tác được định nghĩa trong tệp OpenAPI của bạn. Các phản hồi ví dụ đến từ trường examples trong thông số kỹ thuật của bạn, hoặc từ công cụ mô phỏng thông minh của Apidog nếu không có ví dụ nào được định nghĩa. Bạn có thể ghi đè các quy tắc phản hồi cho mỗi điểm cuối bên trong Apidog mà không cần chạm vào tệp thông số kỹ thuật.
Đối với một nhóm đã quen với việc chạy stoplight mock reference/your-api.yaml cục bộ, sự thay đổi là các kỹ sư QA và nhà phát triển giao diện người dùng của bạn giờ đây sẽ truy cập vào một URL đám mây được chia sẻ thay thế. Điều này đáng để xác thực trong một thử nghiệm để xác nhận rằng nó phù hợp với chính sách truy cập mạng của bạn.
Bước 6: Xây dựng lại bộ thử nghiệm của bạn
Nếu bạn đã sử dụng tính năng kiểm tra hợp đồng của Stoplight hoặc các quy tắc Spectral để linting, những thứ đó cần được xử lý riêng.
Các quy tắc lint Spectral: Stoplight sử dụng Spectral để linting OpenAPI, được cấu hình qua tệp .spectral.yaml. Apidog có các quy tắc lint tích hợp sẵn để tuân thủ OpenAPI, nhưng nó không chạy Spectral trực tiếp. Nếu bạn có các quy tắc Spectral tùy chỉnh mà nhóm của bạn dựa vào, hãy tiếp tục chạy chúng trong CI (GitHub Actions hoặc GitLab CI) độc lập với Apidog. Mức độ bao phủ lint của Apidog và liệu bạn có thể chia sẻ các bộ quy tắc lint tùy chỉnh giữa các dự án hay không đáng để xác minh trong một thử nghiệm dựa trên các yêu cầu quy tắc cụ thể của bạn.
Kiểm thử API: Stoplight Platform bao gồm kiểm thử API dựa trên kịch bản. Trình chạy thử nghiệm của Apidog cho phép bạn xây dựng các kịch bản thử nghiệm một cách trực quan, nối chuỗi các yêu cầu và chạy các xác nhận đối với nội dung phản hồi, tiêu đề và mã trạng thái. Bạn sẽ xây dựng lại những thứ này bên trong Apidog; không có tính năng nhập tự động từ các dự án thử nghiệm Stoplight. Hướng dẫn quy trình làm việc API gốc Git cho thấy cách tích hợp các lần chạy thử nghiệm Apidog vào một pipeline GitHub Actions.
Một ví dụ thực tế: nếu thử nghiệm Stoplight của bạn xác minh rằng POST /orders trả về 201 với tiêu đề location, thì đây là thiết lập thử nghiệm Apidog tương đương trong một CI pipeline sử dụng Apidog CLI:
# .github/workflows/api-tests.yml
name: API contract tests
on:
pull_request:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run Apidog tests
run: |
npx apidog-cli run \
--project-id ${{ secrets.APIDOG_PROJECT_ID }} \
--test-id ${{ secrets.APIDOG_TEST_SUITE_ID }} \
--env production \
--reporter junit \
--output test-results.xml
env:
APIDOG_API_KEY: ${{ secrets.APIDOG_API_KEY }}
- name: Publish test results
uses: mikepenz/action-junit-report@v4
if: always()
with:
report_paths: test-results.xml
Điều này thay thế một lần chạy thử nghiệm Stoplight trong CI và giữ nguyên cấu trúc GitHub Actions hiện có của bạn.
Danh sách kiểm tra đánh giá cho các nhóm doanh nghiệp
Nếu bạn đang di chuyển cho một nhóm lớn hơn (loại đang đánh giá Stoplight Platform thay vì Studio), có những khả năng cụ thể đáng để xác minh trước khi cam kết. Apidog bao gồm các lĩnh vực này, nhưng hành vi chính xác phụ thuộc vào gói và cấu hình không gian làm việc của bạn.
| Khả năng | Điều cần xác minh trong bản dùng thử Apidog |
|---|---|
| Truy cập tài liệu riêng tư | Bạn có thể hạn chế các trang tài liệu cho người dùng đã xác thực hoặc các miền email cụ thể không? Kiểm tra so với các yêu cầu kiểm soát truy cập của bạn. |
| Tái sử dụng Schema/thành phần giữa các dự án | Thư viện components/schemas được chia sẻ có thể được tham chiếu từ nhiều dự án Apidog mà không cần sao chép và dán không? Đáng để thử nghiệm với các tệp schema thực tế của bạn. |
| Chia sẻ quy tắc lint tùy chỉnh | Bạn có thể phân phối một cấu hình lint được chia sẻ (tương đương với .spectral.yaml được chia sẻ) giữa nhiều dự án Apidog trong cùng một không gian làm việc không? |
| Cung cấp SSO/SCIM | SSO của Apidog có hỗ trợ nhà cung cấp danh tính của bạn không? Xác nhận mức độ chi tiết cung cấp SCIM phù hợp với quy trình quản lý vòng đời người dùng của bạn. |
| Nhật ký kiểm toán | Nhật ký kiểm toán ghi lại những sự kiện nào và ở định dạng nào? Xác minh nó đáp ứng các yêu cầu tuân thủ hoặc xem xét bảo mật của bạn. |
Hãy coi đây là các nhiệm vụ đánh giá, không phải là rào cản. Hầu hết có thể được xác nhận trong một bản dùng thử hai tuần với một dự án đại diện.
Câu hỏi thường gặp
Tôi có thể tiếp tục sử dụng Spectral với Apidog không?
Có. Chạy Spectral trong pipeline CI của bạn độc lập với Apidog. Tệp .spectral.yaml của bạn vẫn ở trong kho lưu trữ và tác vụ CI của bạn (GitHub Actions, GitLab CI) sẽ lint tệp OpenAPI trên mỗi PR. Apidog xử lý tài liệu, mô phỏng và kiểm thử; Spectral xử lý linting. Chúng không xung đột. Xem tài liệu của Spectral để biết các tùy chọn tích hợp CI.
Liệu các đường dẫn $ref của tôi có bị hỏng khi tôi kết nối kho lưu trữ với Apidog không?
Sẽ không nếu các đường dẫn của bạn chính xác trong tệp spec. Apidog giải quyết $ref tương đối với vị trí của tệp OpenAPI gốc. Nếu spec của bạn nói $ref: '../models/error.json' và thư mục models/ nằm một cấp trên reference/, Apidog sẽ theo đường dẫn tương đối đó trong kho lưu trữ. Hãy thử nghiệm với một spec sử dụng các tham chiếu bên ngoài trước.
Apidog Spec-First Mode có hỗ trợ GitLab cũng như GitHub không?
Có, cả GitHub và GitLab đều được hỗ trợ. Quy trình kết nối là như nhau; bạn xác thực bằng tài khoản GitLab của mình và chọn kho lưu trữ và nhánh. Để biết thêm về các tùy chọn kiểm soát phiên bản, hướng dẫn kiểm soát phiên bản OpenAPI với Git trình bày chi tiết các chiến lược nhánh.
Điều gì xảy ra với URL tài liệu Stoplight hiện có của tôi sau khi di chuyển?
Các URL tài liệu được lưu trữ bởi Stoplight (docs.stoplight.io/your-org/your-api) sẽ ngừng hoạt động khi bạn hủy đăng ký Stoplight. Apidog cung cấp cho tài liệu của bạn một URL mới trên một subdomain mà bạn cấu hình. Thiết lập chuyển hướng ở lớp DNS hoặc CDN nếu bạn có các liên kết bên ngoài trỏ đến các trang tài liệu Stoplight của bạn.
Tôi có cần xóa .stoplight.json và toc.json khỏi kho lưu trữ không?
Không. Apidog bỏ qua các tệp mà nó không nhận ra. Hãy giữ chúng nguyên nếu việc xóa chúng sẽ gây ra xung đột hợp nhất hoặc nhầm lẫn. Khi nhóm đã hoàn toàn chuyển sang Apidog, bạn có thể xóa chúng trong một PR dọn dẹp, nhưng điều đó không bắt buộc để quá trình di chuyển hoạt động.
Kết luận
Di chuyển từ Stoplight sang Apidog không có nghĩa là bắt đầu lại từ đầu. Các thông số kỹ thuật OpenAPI của bạn vẫn nằm trong Git, quy trình làm việc nhánh của bạn vẫn nguyên vẹn và cấu trúc thư mục reference/, models/ và docs/ của bạn ánh xạ rõ ràng đến những gì Apidog mong đợi. Việc di chuyển là một cuộc hoán đổi cấu hình: thay thế .stoplight.json và toc.json bằng cài đặt dự án Apidog, kết nối kho lưu trữ của bạn thông qua Chế độ Spec-First và xây dựng lại các kịch bản thử nghiệm của bạn bên trong trình chạy thử nghiệm của Apidog.
Bắt đầu di chuyển Stoplight của bạn bằng cách kết nối Apidog Spec-First Mode với kho lưu trữ OpenAPI GitHub hoặc GitLab hiện có của bạn. Không cần tải lại, không bị khóa, cùng một lịch sử Git. Tải xuống Apidog để bắt đầu và sử dụng một dự án API đại diện cho bản dùng thử của bạn để thực hiện danh sách kiểm tra đánh giá ở trên với dữ liệu thực tế của bạn.