Cách chuyển từ Redocly sang Apidog mà không mất quy trình Docs-as-Code

Nếu bạn đang chạy cổng thông tin dành cho nhà phát triển (developer portal) trên Redocly, bạn vốn đã làm việc theo cách mà hầu hết các đội ngũ API mong muốn: openapi.yaml nằm trong Git, các hướng dẫn viết bằng Markdown, và chỉ cần push là tài liệu được cập nhật. Nỗi lo khi đổi công cụ là đánh mất vòng lặp đó và rốt cuộc phải chỉnh sửa tài liệu bằng tay trên giao diện web.

Bạn không cần phải như vậy. Chế độ Spec-first Mode của Apidog giữ nguyên spec và các file Markdown của bạn trong cùng một repository, đồng bộ mỗi lần push thông qua webhook, và xuất bản một cổng thông tin với các hướng dẫn cùng phần tham chiếu API trong cùng một thanh điều hướng bên. Bài viết này sẽ hướng dẫn từng bước quá trình chuyển đổi, bao gồm cả phần không thể tự động chuyển sang: nội dung dài mà nhiều người dùng Redocly thường để trong info.description và tags[].description.

Nếu bạn vẫn đang cân nhắc giữa các công cụ, hãy bắt đầu với Apidog vs. Redocly hoặc danh sách rộng hơn về các lựa chọn thay thế Redocly. Bài viết này giả định rằng bạn đã chọn Apidog và muốn chuyển đổi mà không làm gián đoạn quy trình làm việc của mình.

Những gì giữ nguyên và những gì không

Chúng tôi đã thử nghiệm quá trình chuyển đổi này với một spec thực tế đang chạy production: OpenAPI 3.0.3, 62 thao tác (operation) trải khắp 13 tag, với nội dung bắt đầu, xác thực và tích hợp được viết thẳng vào các trường description của spec. Đây là những gì đã xảy ra khi import.

Phần tham chiếu API chuyển sang mà không cần chỉnh sửa gì. Khoảng trống nằm ở nội dung dạng tường thuật.

Vì sao các trường description của bạn không hiển thị giống nhau

Redoc, trình render đứng sau phần tài liệu tham chiếu của Redocly, coi info.description như một tài liệu thu nhỏ. Mọi tiêu đề Markdown bên trong nó đều trở thành một mục trong thanh điều hướng bên, vì vậy các đội ngũ thường viết toàn bộ hướng dẫn “Bắt đầu” và “Xác thực” ở đó. Phần mô tả của tag được render thành văn bản giới thiệu ở đầu mỗi nhóm tag.

Đó là một quy ước của Redoc, không phải một phần của Đặc tả OpenAPI. Đặc tả chỉ định nghĩa description là một chuỗi CommonMark. Apidog, giống như hầu hết các cổng thông tin khác, giữ các hướng dẫn dưới dạng tài liệu Markdown độc lập và giữ spec cho phần tham chiếu. Một lần xuất bản mặc định sau khi import sẽ chỉ hiển thị phần tham chiếu API, mà không có các hướng dẫn bạn đã viết trong các trường description.

Cách khắc phục là một thao tác di chuyển chỉ làm một lần: tách nội dung đó ra khỏi YAML và đưa vào các file Markdown nằm cạnh nó. Sau đó, mọi thứ vẫn vận hành theo hướng Git.

Bố cục repository đích

Đây là cấu trúc mà chúng tôi đã kiểm chứng:

your-repo/
├── openapi.yaml              # source of truth for the API reference
└── docs/
    ├── getting-started.md
    ├── authentication.md
    └── embed-integration-guide.md

openapi.yaml điều khiển phần tham chiếu API. Mỗi file trong docs/ trở thành một trang trong thanh điều hướng của cổng thông tin. Các hình ảnh được tham chiếu bởi những file Markdown đó có thể nằm cùng trong repo và được đồng bộ cùng chúng.

Nếu bạn đã dùng sidebars.yaml của Redocly để sắp xếp thứ tự điều hướng, hãy giữ nó lại làm tham chiếu. Bạn sẽ thiết lập đúng thứ tự đó một lần trong phần cài đặt docs site của Apidog.

Chuyển đổi từng bước

1. Kiểm tra nội dung bên trong các trường description của bạn

Trước khi di chuyển bất cứ thứ gì, hãy xem có bao nhiêu nội dung nằm trong spec. Với yq:

# How long is the top-level description?
yq '.info.description' openapi.yaml | wc -w

# Which headings does it contain? Each one is a Redoc sidebar entry today.
yq '.info.description' openapi.yaml | grep -E '^#{1,3} '

# Which tags carry a description?
yq '.tags[] | select(.description != null) | .name' openapi.yaml

Danh sách tiêu đề chính là danh sách file docs/ tương lai của bạn. Trong thử nghiệm của chúng tôi, info.description được tách thành hai file Markdown, và các mô tả tag trở thành các trang giới thiệu cho từng thư mục cộng thêm một file Markdown nữa.

2. Tách info.description thành các file Markdown

Sao chép từng phần cấp cao nhất vào file riêng của nó trong docs/. Giữ nguyên tiêu đề, mẫu code và liên kết. Sau đó thu gọn info.description trong spec thành một đoạn tóm tắt duy nhất, để nội dung chỉ tồn tại ở một nơi.

Hãy chú ý hai tính năng đặc thù của Redoc khi sao chép:

• Các thẻ Redoc như <SecurityDefinitions /> và tương tự sẽ không render bên ngoài Redoc. Hãy thay chúng bằng một đoạn viết ngắn liên kết tới các security scheme trong phần tham chiếu.
• Các liên kết như #tag/Payments trỏ tới các neo (anchor) của Redoc. Hãy cập nhật chúng thành URL trang tài liệu hoặc thư mục tương ứng trong Apidog sau lần xuất bản đầu tiên.

3. Kết nối repository trong Spec-first Mode

Tạo một project trong Spec-first Mode, kết nối repository của bạn (GitHub, GitLab, Azure DevOps hoặc Bitbucket), trỏ nó tới openapi.yaml và thư mục docs/, rồi cài đặt webhook. Từ đó trở đi, mỗi lần push lên nhánh được theo dõi sẽ cập nhật project.

Sau lần đồng bộ đầu tiên, workspace Specs sẽ hiển thị spec của bạn và phần còn lại của repository. Tab APIs liệt kê các operation được phân tích từ openapi.yaml, Docs chứa các trang Markdown của bạn, và All files phản chiếu toàn bộ repo.

Webhook chính là thứ giữ cho quy trình này vận hành theo kiểu docs-as-code. Không có nó, bạn sẽ phải kích hoạt đồng bộ bằng tay. Để nhắc lại vì sao điều này quan trọng, hãy xem hướng dẫn của chúng tôi về docs as code.

4. Xuất bản docs site và thiết lập điều hướng

Xuất bản một docs site từ project và sắp xếp thanh điều hướng bên. Thứ tự mà hầu hết người dùng Redocly muốn, và cũng là thứ tự chúng tôi đã tái tạo, là:

1. Bắt đầu (Getting Started)
2. Xác thực (Authentication)
3. Các hướng dẫn tích hợp
4. Tham chiếu API (các thư mục endpoint từ tag của bạn)

Các trang Markdown và thư mục API kết hợp tự do trong cùng một cây, nên bạn có thể dựng gần giống thanh điều hướng Redocly hiện tại của mình.

5. Thêm tên miền tùy chỉnh của bạn

Trỏ một bản ghi CNAME như developers.example.com tới docs site. Tên miền tùy chỉnh có sẵn ở gói Free.

Để coding agent của bạn chuyển các mô tả tag bằng Apidog CLI

Mô tả tag là phần tẻ nhạt nhất. Mười ba tag nghĩa là mười ba lần copy-paste, và bạn sẽ phải làm lại mỗi khi một mô tả tag thay đổi trong quá trình chuyển đổi. Hãy giao việc đó cho coding agent của bạn.

Apidog CLI cho phép Claude Code, Codex, Cursor hoặc bất kỳ agent chạy trên terminal nào truy cập có cấu trúc dưới dạng JSON vào project của bạn, bao gồm cả các thư mục endpoint. Hãy thiết lập một lần:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_ACCESS_TOKEN>
npx -y skills add https://apidog.com

Dòng cuối cùng cài đặt skill Apidog để agent của bạn biết các lệnh mà không phải đoán. Hướng dẫn cài đặt đề cập đến token và các triển khai riêng tư (private deployment).

Sau đó, đưa cho agent của bạn một câu lệnh:

Đọc openapi.yaml. Với mỗi tag có mô tả, hãy tìm thư mục endpoint tương ứng trong project Apidog <PROJECT_ID> và đặt mô tả của thư mục đó bằng mô tả của tag. Kiểm tra (validate) từng payload bằng apidog cli-schema validate folder-update trước khi ghi. Cho tôi xem danh sách các thư mục bạn đã thay đổi.

Đây là những gì agent sẽ chạy:

# Find the folder IDs that correspond to your tags
apidog folder list --project <PROJECT_ID> --type endpoint

# Check the payload shape instead of guessing it
apidog cli-schema get folder-update

# For each tag: write {"description": "..."} to a file, validate, then update
apidog cli-schema validate folder-update --file ./payments-folder.json
apidog folder update <FOLDER_ID> --project <PROJECT_ID> --type endpoint \
  --file ./payments-folder.json

Schema folder-update chấp nhận name, parentId và description, và description được hỗ trợ trên các thư mục endpoint và test-scenario. Với những hướng dẫn không thuộc về một tag duy nhất, agent có thể dùng apidog doc list và apidog doc create theo cách tương tự, sau khi đọc apidog cli-schema get doc-create.

Để hiển thị phần giới thiệu của một thư mục trên site đã xuất bản, hãy đặt Folder Contents Displaying Setting trong phần cài đặt của thư mục đó, mục Documentation Settings after Publication.

Một lưu ý thẳng thắn: việc hiển thị mô tả tag thành các trang giới thiệu theo từng danh mục là làm được, nhưng nó dựa vào một lối đi ít được ghi chép rõ ràng. Hãy thử trên hai hoặc ba thư mục trong workspace của riêng bạn trước khi phụ thuộc vào nó cho tất cả. Để biết thêm về các công việc liên quan đến spec do agent thực hiện, hãy xem dùng Apidog CLI trong Claude Code và để agent cập nhật spec API của bạn.

Những gì nằm ngoài Git

Một project Spec-first giữ API và các file Markdown của bạn trong Git. Một vài cài đặt của cổng thông tin nằm trong giao diện Apidog và không được quản lý phiên bản:

Đây là những mục chỉ cần thiết lập một lần. Bạn chỉ động tới chúng khi thêm một mục cấp cao nhất mới, chứ không phải mỗi lần thay đổi nội dung. Redocly giữ nhiều thứ trong số này trong redocly.yaml và sidebars.yaml, nên nếu hiện nay bạn xem xét các thay đổi điều hướng qua pull request, hãy chuẩn bị tinh thần rằng việc đó sẽ chuyển sang giao diện UI.

Gói dịch vụ và giá

Thiết lập được mô tả ở đây phù hợp với gói Free, bao gồm cả tên miền tùy chỉnh. Gói Free hỗ trợ tối đa 4 thành viên nhóm. Các gói trả phí bổ sung những thứ như nhiều docs site trên mỗi project và các kiểm soát hiển thị tùy chỉnh. Hãy xem bảng giá Apidog để biết các giới hạn hiện tại.

Redocly vs. Apidog sau khi chuyển đổi

Sự đánh đổi rất đơn giản. Bạn mất phần điều hướng được định nghĩa bằng YAML. Bạn nhận được khả năng kiểm thử, mock và một CLI thân thiện với agent trên chính spec mà tài liệu của bạn lấy làm nguồn. Để xem so sánh từng lệnh CLI một, hãy đọc Apidog CLI vs Redocly CLI.

Câu hỏi thường gặp

Các URL được host trên Redocly của tôi có tiếp tục hoạt động không? Không tự động. Đường dẫn trang sẽ thay đổi. Nếu cổng thông tin cũ của bạn có những URL hướng dẫn có lượng truy cập cao, hãy thêm chuyển hướng (redirect) ở tầng DNS hoặc proxy cho các trang chính sau khi bạn đổi tên miền.

Tôi có phải viết lại spec OpenAPI của mình không? Không. Spec được import nguyên trạng. Bạn chỉ cần chuyển nội dung dạng tường thuật ra khỏi info.description và tags[].description vào các file Markdown.

Tôi có thể giữ x-tagGroups không? Hãy dùng thư mục để nhóm thay vào đó. Mỗi tag trở thành một thư mục, và bạn có thể lồng các thư mục vào nhau để tái tạo các nhóm tag của mình.

Điều này so với việc chuyển từ Stoplight thì thế nào? Hình thức tương tự: spec trong Git, Markdown nằm cạnh nó, đồng bộ bằng webhook. Hãy xem cách chuyển từ Stoplight sang Apidog nếu bạn dùng cả hai công cụ.

Nếu một bước nào đó hoạt động khác trong workspace của tôi thì sao? Kết quả của chúng tôi đến từ một môi trường thử nghiệm. Hãy chạy lại quá trình import trên một nhánh trước và so sánh cổng thông tin đã xuất bản với cổng hiện tại của bạn trước khi đổi DNS.

Hoàn tất việc chuyển đổi trong một buổi chiều

Chuyển từ Redocly sang Apidog chủ yếu là một thao tác di chuyển nội dung. Spec của bạn được import nguyên trạng. Các hướng dẫn của bạn được chuyển ra khỏi các trường description vào thư mục docs/ một lần. Sau đó, một webhook giữ mọi thứ đồng bộ. Hãy để agent của bạn xử lý công việc lặp đi lặp lại là mô tả tag bằng Apidog CLI, và dành thời gian của chính bạn để kiểm tra cổng thông tin đã xuất bản từng trang một.

Tải Apidog và kết nối repo của bạn với Spec-first Mode để bắt đầu quá trình chuyển đổi.