Cách di chuyển từ Swagger CLI sang Apidog CLI

Nếu bạn vẫn chạy các lệnh swagger-cli validate và swagger-cli bundle trong pipeline của mình, thì bạn đang duy trì một script xung quanh một công cụ mà không ai còn duy trì nữa. Kho lưu trữ swagger-cli trên GitHub hiện đã nói rõ: gói này không còn được duy trì, README nêu gánh nặng phải theo kịp một lượng người dùng khổng lồ nhưng đóng góp ít trở lại, và nó chỉ người dùng mới đến các lựa chọn khác.

Vì vậy, đây là thời điểm tốt để quyết định quy trình làm việc với spec của bạn sẽ nằm ở đâu tiếp theo. Hướng dẫn này là một sổ tay di chuyển, không phải hướng dẫn sử dụng. Nếu bạn chưa sẵn sàng chuyển đổi và chỉ muốn tiếp tục sử dụng công cụ cũ, hướng dẫn Swagger CLI sẽ giải thích chi tiết về validate và bundle. Bài viết này nói về việc rời đi, cụ thể là cách di chuyển Swagger CLI sang Apidog CLI mà không làm gián đoạn CI của bạn.

Tải xuống Apidog nếu bạn muốn làm theo với các lệnh thực tế. Bắt đầu miễn phí, không yêu cầu thẻ tín dụng.

button

Tại sao nên di chuyển ngay bây giờ

Đầu tiên là câu trả lời trung thực: swagger-cli đã bị ngừng hỗ trợ và không được duy trì trong một thời gian. Nó vẫn hoạt động. Rất nhiều pipeline vẫn đang gọi nó hôm nay. Nhưng một công cụ không được sửa lỗi hoặc cập nhật spec là nợ kỹ thuật tồn đọng trong bản dựng của bạn, và chính những người duy trì cũng khuyên bạn nên chuyển đổi.

Họ đặc biệt chỉ ra một công cụ kế nhiệm. Redocly CLI là lựa chọn thay thế trực tiếp gần nhất nếu tất cả những gì bạn từng muốn là xác thực và gói trong terminal. Nó là mã nguồn mở, ưu tiên code và chạy trực tiếp trên terminal. Lệnh lint của nó thực hiện xác thực cấu trúc, và redocly bundle theo dõi các con trỏ $ref chính xác như swagger-cli bundle đã làm. Nếu mục tiêu duy nhất của bạn là một sự hoán đổi 1:1 giữ spec dưới dạng một tệp phẳng trong kho lưu trữ của bạn, Redocly là lựa chọn tự nhiên, và Redocly xuất bản hướng dẫn di chuyển của riêng mình với ánh xạ lệnh. Không có gì phải xấu hổ khi đi theo con đường đó.

Apidog dành cho một mục tiêu khác. Di chuyển sang Apidog CLI khi bạn muốn spec làm được nhiều hơn là chỉ nằm trong một tệp. Thay vì xác thực và gói một tài liệu tĩnh, bạn đưa toàn bộ định nghĩa vào một không gian làm việc sống động, sau đó xác thực nó khi nhập, xuất một tệp hợp nhất khi bạn cần, và tùy chọn giả lập API, chạy các kịch bản kiểm thử chống lại nó, và xuất bản tài liệu từ cùng một nguồn. swagger-cli chỉ từng làm hai việc. Apidog bao quát phần còn lại của vòng đời.

Hãy chọn dựa trên sự phù hợp, không phải theo xu hướng. Nếu bạn muốn một linter và bundler nhẹ, dựa trên cấu hình, chạy hoàn toàn từ terminal, Redocly thắng. Nếu bạn muốn có một nền tảng duy nhất cho thiết kế, giả lập, kiểm thử và tài liệu thay vì phải kết nối nhiều công cụ lại với nhau, Apidog thắng.

Những gì swagger-cli đã làm so với những gì Apidog CLI làm

swagger-cli chỉ có chính xác hai lệnh:

swagger-cli validate <file> kiểm tra một tài liệu Swagger 2.0 hoặc OpenAPI 3.0 dựa trên lược đồ và xác minh các con trỏ $ref của nó đã được phân giải.
swagger-cli bundle <file> theo dõi các con trỏ $ref đó và kết hợp một định nghĩa đa tệp thành một tệp duy nhất, với các tùy chọn cho đường dẫn đầu ra (-o), loại (-t json|yaml), phân giải tham chiếu đầy đủ (-r) và thụt lề (-f).

Đó là toàn bộ công cụ. Nó không lint theo quy tắc kiểu, tạo tài liệu, chạy kiểm thử hoặc giả lập bất cứ thứ gì.

Apidog CLI ánh xạ hai công việc đó vào hai lệnh của nó, sau đó tiếp tục:

apidog import đưa một định nghĩa vào dự án Apidog và xác thực nó trong quá trình nhập. Các spec đa tệp sẽ có các con trỏ $ref được phân giải thành các tài nguyên hợp nhất một cách tự động. Đây là bước xác thực của bạn, cộng thêm việc nhập.
apidog export xuất một tệp hợp nhất duy nhất từ dự án, và cho phép bạn chọn phiên bản OpenAPI khi xuất. Đây là bước gói của bạn, cộng thêm khả năng nâng cấp phiên bản tùy chọn và khả năng xuất tài liệu HTML hoặc Markdown.
apidog run thực thi các kịch bản và bộ kiểm thử, với JUnit và các báo cáo khác cho CI. swagger-cli không có công cụ tương đương.
Các lệnh tài nguyên (endpoint, schema, mock, environment, branch, v.v.) quản lý dự án từ terminal sau khi spec đã được nhập.

Một điểm chính xác để ánh xạ được trung thực: Apidog xác thực cấu trúc khi nhập, nhưng nó không phải là một linter hướng dẫn kiểu có thể cấu hình. Không có apidog lint và không có bộ quy tắc tùy chỉnh. Nếu bạn dựa vào linting có ý kiến, phần đó không được chuyển đổi, và phần Những gì bạn nhận được ngoài validate và bundle sẽ đề cập cách xử lý nó.

Cài đặt và đăng nhập

Apidog CLI được phân phối dưới dạng gói npm. Cài đặt nó trên toàn cầu:

npm install -g apidog-cli@latest

Sau đó xác thực bằng mã thông báo truy cập:

apidog login --with-token <TOKEN>

Bạn lấy mã thông báo từ ứng dụng hoặc web Apidog: nhấp vào ảnh đại diện của bạn, đi tới Cài đặt tài khoản (Account Settings), sau đó Mã thông báo truy cập API (API Access Token), và tạo một cái. CLI lưu trữ nó trong ~/.apidog/config.toml. Hãy xử lý nó như bất kỳ bí mật nào khác. Không in nó trong nhật ký hoặc commit nó vào kho lưu trữ của bạn.

Nếu bạn muốn biết mọi cờ và một chuyến tham quan sâu hơn, hướng dẫn hoàn chỉnh Apidog CLI và tài liệu chính thức Apidog CLI bao quát toàn bộ bề mặt. Đối với việc di chuyển này, cài đặt và đăng nhập là tất cả những gì bạn cần để bắt đầu.

Bảng ánh xạ lệnh

Đây là bản dịch trực tiếp từ swagger-cli sang Apidog CLI. Một điểm khác biệt về cấu trúc: Apidog hoạt động trên một dự án, vì vậy hầu hết các luồng là nhập-sau-đó-xuất hơn là một lệnh duy nhất trên một tệp rời rạc.

Lệnh swagger-cli	Tương đương với Apidog CLI	Những thay đổi
`swagger-cli validate openapi.yaml`	`apidog import --project <id> --format openapi --file ./openapi.yaml`	Xác thực spec khi nhập; các spec không hợp lệ sẽ làm cho lệnh thất bại
`swagger-cli bundle openapi.yaml -o out.json`	`apidog import ...` sau đó `apidog export --project <id> --format openapi --output ./out.json`	Gói hóa trở thành một thao tác xuất từ dự án; `$refs` đã được phân giải khi nhập
`swagger-cli bundle -t yaml`	`apidog export --project <id> --format openapi --output ./out.yaml`	Định dạng đầu ra theo tệp bạn ghi
(không có công cụ tương đương)	`apidog export --project <id> --format openapi --output ./out.json --oas-version 3.1`	Nâng cấp spec 2.0 hoặc 3.0 lên 3.1 khi xuất
(không có công cụ tương đương)	`apidog export --project <id> --format html --output ./docs.html`	Xuất tài liệu HTML độc lập
(không có công cụ tương đương)	`apidog export --project <id> --format markdown --output ./docs.md`	Xuất tài liệu Markdown
(không có công cụ tương đương)	`apidog run --project <id> -t <scenarioId> -e <envId> -r junit`	Chạy kiểm thử API trong CI

Hai ô quan trọng nhất cho việc di chuyển là hai hàng đầu tiên. Mọi thứ bên dưới chúng là khả năng mà swagger-cli chưa bao giờ có. Cờ --oas-version là bản nâng cấp rõ ràng nhất: swagger-cli có thể gói một tệp Swagger 2.0, nhưng nó không thể biến nó thành OpenAPI 3.1. Apidog có thể, khi xuất, điều này rất tiện lợi khi bạn đang hiện đại hóa một hợp đồng cũ. Nếu mục tiêu của bạn là xuất tài liệu cụ thể, xuất OpenAPI sang Markdown sẽ đi sâu hơn vào định dạng đó.

Di chuyển từng bước

Đây là toàn bộ lộ trình từ thiết lập swagger-cli sang một luồng Apidog hoạt động.

1. Lấy ID dự án của bạn. Tạo hoặc mở một dự án trong ứng dụng Apidog. ID dự án xuất hiện trong cài đặt dự án và trong URL. Bạn sẽ truyền nó cho mọi lệnh CLI thông qua --project.

2. Nhập spec gốc. Chỉ Apidog đến tệp đầu vào của định nghĩa của bạn. Các spec đa tệp với các con trỏ $ref sẽ tự động được phân giải, vì vậy bạn chỉ cần nhập tệp gốc và Apidog sẽ kéo phần còn lại vào:

apidog import --project 123456 --format openapi --file ./openapi.yaml

Nếu spec bị định dạng sai hoặc có $ref bị treo, quá trình nhập sẽ thất bại. Lỗi đó là cổng xác thực của bạn, cùng công việc mà swagger-cli validate từng làm, giờ đã được tích hợp vào quá trình nhập.

3. Xác minh trong ứng dụng. Mở dự án và xác nhận các endpoint, schema và tham số của bạn đã được nhập đúng cách. Việc kiểm tra trực quan này không có công cụ tương đương trong swagger-cli, và đáng để thực hiện một lần trong quá trình di chuyển để xác nhận rằng quá trình nhập đã diễn ra như bạn mong đợi.

4. Xuất tệp hợp nhất. Khi bạn cần một tệp phẳng duy nhất (cho một công cụ downstream, một công cụ tạo client hoặc một artifact), hãy xuất nó. Chọn phiên bản OpenAPI bạn muốn:

apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1

Điều đó thay thế lệnh swagger-cli bundle. Các con trỏ $ref đã được phân giải khi nhập, vì vậy việc xuất là đầu ra hợp nhất, một tệp của bạn.

5. Kết nối nó vào CI. Thay thế bước swagger-cli cũ của bạn bằng nhập (xác thực khi nhập) và xuất (gói), và thêm một lần chạy kiểm thử nếu bạn có các kịch bản. Phần tiếp theo có một ví dụ đầy đủ về GitHub Actions.

Ví dụ CI với GitHub Actions

Quy trình làm việc này cài đặt CLI, đăng nhập bằng mã thông báo từ bí mật kho lưu trữ, nhập spec để xác thực, xuất một artifact hợp nhất, sau đó chạy các kịch bản kiểm thử với trình báo cáo JUnit để một kiểm thử thất bại sẽ làm thất bại kiểm tra và chặn PR.

name: API spec check

on:
  pull_request:
    branches: [main]

jobs:
  apidog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Apidog CLI
        run: npm install -g apidog-cli@latest

      - name: Log in
        run: apidog login --with-token ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Import spec (validates on import)
        run: apidog import --project 123456 --format openapi --file ./openapi.yaml

      - name: Export consolidated spec
        run: apidog export --project 123456 --format openapi --output ./dist/openapi.json --oas-version 3.1

      - name: Run test scenarios
        run: apidog run --project 123456 -t 7890 -e 4567 -r "cli,junit" --out-dir ./reports

Lưu mã thông báo dưới dạng APIDOG_ACCESS_TOKEN trong bí mật kho lưu trữ của bạn để nó không bao giờ xuất hiện trong nhật ký. Trình báo cáo -r "cli,junit" ghi một tệp XML JUnit mà CI của bạn có thể hiển thị dưới dạng báo cáo kiểm thử, và một kịch bản thất bại sẽ trả về mã thoát khác không, chặn việc hợp nhất. Để có các mẫu pipeline sâu hơn, hãy xem hướng dẫn CI/CD của Apidog CLI, và để thiết lập dành riêng cho runner, hãy xem hướng dẫn Apidog CLI với GitHub Actions.

Những gì bạn nhận được ngoài validate và bundle

Đây là nơi việc di chuyển mang lại lợi ích, và nơi sự trung thực là quan trọng nhất.

Máy chủ giả lập. Khi spec của bạn nằm trong một dự án, Apidog có thể phục vụ các phản hồi giả lập từ đó. Bạn có thể phát triển giao diện người dùng dựa trên API trước khi backend tồn tại. swagger-cli chưa bao giờ chạm đến hành vi thời gian chạy.

Kịch bản kiểm thử tự động. apidog run thực thi các yêu cầu thực tế đối với một API đang chạy và xác nhận các phản hồi. Bạn xây dựng các kịch bản trực quan trong ứng dụng, sau đó chạy chúng không giao diện trong CI. Điều đó lấp đầy khoảng trống mà swagger-cli đã bỏ ngỏ: một spec hợp lệ cho bạn biết rằng hợp đồng được định dạng tốt, chứ không phải là việc triển khai khớp với nó.

Tài liệu được lưu trữ và xuất. apidog export --format html hoặc --format markdown tạo tài liệu trực tiếp từ cùng một nguồn. Không có bước xây dựng tài liệu riêng biệt để duy trì.

Bây giờ là giới hạn trung thực. Apidog CLI không có một linter hướng dẫn kiểu ưu tiên code, có thể cấu hình với các bộ quy tắc tùy chỉnh. Nó xác thực cấu trúc khi nhập, nhưng bạn không thể tạo các quy tắc kiểu Spectral hoặc Redocly thông qua CLI, và không có lệnh apidog lint. Nếu thiết lập cũ của bạn dựa vào việc linting chặt chẽ (đặt tên nhất quán, mô tả bắt buộc, ví dụ trên mọi phản hồi), hãy giữ một linter chuyên dụng trong quy trình. Kết hợp Apidog với Spectral hoặc Redocly cho việc đó, và chạy nó như một bước CI riêng biệt. Hướng dẫn thiết lập linter OpenAPI bao gồm cách kết nối một linter. Sử dụng cả hai không phải là mâu thuẫn: lint bằng một công cụ chuyên biệt, sau đó quản lý vòng đời trong Apidog.

button