Blog

Hướng Dẫn Redocly: Cách Sử Dụng Redocly CLI

Mark Ponomarev

Mark Ponomarev

9 tháng 6 2025

Hướng Dẫn Redocly: Cách Sử Dụng Redocly CLI

Chào mừng bạn đến với hướng dẫn toàn diện về Redocly CLI! Redocly CLI là một công cụ dòng lệnh mạnh mẽ, tất cả trong một dành cho các định nghĩa OpenAPI và Swagger. Nó giúp bạn xây dựng, quản lý và kiểm tra chất lượng mô tả API của mình trong suốt vòng đời API. Cho dù bạn là nhà phát triển, người viết tài liệu kỹ thuật hay quản lý sản phẩm API, công cụ này đều có ích cho bạn.

Hướng dẫn này nhằm mục đích đi sâu vào Redocly CLI, đưa bạn từ người mới bắt đầu trở thành người dùng tự tin. Chúng tôi sẽ đề cập đến mọi thứ từ cài đặt đến các tính năng nâng cao như quy tắc lint tùy chỉnh và tích hợp CI/CD. Đến cuối hướng dẫn này, bạn sẽ có thể tích hợp Redocly CLI vào quy trình làm việc hàng ngày của mình để cải thiện chất lượng và tài liệu API của bạn.

💡
Bạn muốn một công cụ Kiểm tra API tuyệt vời tạo ra Tài liệu API đẹp mắt?

Bạn muốn một nền tảng tích hợp, Tất cả trong một để Nhóm phát triển của bạn làm việc cùng nhau với năng suất tối đa?

Apidog đáp ứng mọi yêu cầu của bạn và thay thế Postman với mức giá phải chăng hơn nhiều!
button

Redocly CLI là gì?

Như đã nêu trong tài liệu chính thức, Redocly CLI là "tiện ích OpenAPI tất cả trong một" của bạn. Nó hỗ trợ OpenAPI 3.1, 3.0, 2.0 (Swagger cũ), AsyncAPI và hơn thế nữa. Nó được thiết kế để giúp bạn với:

Công cụ này được xây dựng với hiệu suất và trải nghiệm người dùng, cung cấp khả năng thực thi nhanh chóng và thông báo lỗi dễ đọc.

Tại sao nên sử dụng Redocly CLI?

Trong thế giới ưu tiên API ngày nay, việc duy trì các định nghĩa API chất lượng cao là rất quan trọng. Redocly CLI giúp bạn đạt được điều này bằng cách:

Hướng dẫn này sẽ bao gồm những gì

Hướng dẫn này được cấu trúc để cung cấp hướng dẫn từng bước để làm chủ Redocly CLI. Đây là những gì chúng ta sẽ đề cập:

Hãy bắt đầu nào!

Chương 1: Bắt đầu với Redocly CLI

Chương này sẽ hướng dẫn bạn qua các bước đầu tiên sử dụng Redocly CLI, từ cài đặt đến chạy lệnh đầu tiên.

Điều kiện tiên quyết

Trước khi bắt đầu, hãy đảm bảo bạn đã cài đặt những thứ sau trên hệ thống của mình:

Cài đặt

Bạn có một số tùy chọn để cài đặt và sử dụng Redocly CLI. Chọn tùy chọn phù hợp nhất với nhu cầu của bạn.

Sử dụng npx (Khuyến nghị cho việc sử dụng nhanh)

Nếu bạn chỉ muốn dùng thử Redocly CLI mà không cần cài đặt toàn cục, bạn có thể sử dụng npx, trình chạy gói npm. Lệnh này sẽ tải xuống và chạy phiên bản mới nhất của Redocly CLI.

npx @redocly/cli@latest --version

Để sử dụng bất kỳ lệnh redocly nào, chỉ cần thêm tiền tố npx @redocly/cli@latest. Ví dụ:

npx @redocly/cli@latest lint openapi.yaml

Đây là cách tuyệt vời để sử dụng Redocly CLI trong môi trường CI/CD hoặc nếu bạn không muốn làm lộn xộn hệ thống của mình với các gói toàn cục.

Cài đặt toàn cục với npm

Đối với việc sử dụng thường xuyên, cài đặt toàn cục tiện lợi hơn. Nó làm cho lệnh redocly có sẵn trực tiếp trong terminal của bạn.

npm install -g @redocly/cli@latest

Sau khi cài đặt, bạn có thể xác minh bằng cách kiểm tra phiên bản:

redocly --version

Bây giờ bạn có thể chạy các lệnh như thế này:

redocly lint openapi.yaml

Sử dụng Docker

Nếu bạn thích sử dụng Docker, Redocly cung cấp một ảnh Docker được xây dựng sẵn. Điều này hữu ích cho việc cách ly công cụ khỏi môi trường cục bộ của bạn.

Đầu tiên, kéo ảnh từ Docker Hub:

docker pull redocly/cli

Để chạy một lệnh, bạn cần gắn thư mục làm việc hiện tại của mình (nơi chứa các tệp API) làm volume vào container Docker.

docker run --rm -v $PWD:/spec redocly/cli lint /spec/openapi.yaml

Trong lệnh này, $PWD đề cập đến thư mục hiện tại của bạn, được gắn vào thư mục /spec bên trong container. Sau đó, bạn cần tham chiếu đến các tệp của mình bằng đường dẫn /spec.

Cấu trúc lệnh cơ bản

Cấu trúc cơ bản để sử dụng Redocly CLI là:

redocly [command] [arguments] [options]

Bạn luôn có thể nhận trợ giúp cho một lệnh cụ thể bằng cách sử dụng tùy chọn --help:

redocly lint --help

Bây giờ bạn đã cài đặt Redocly CLI và hiểu cấu trúc lệnh cơ bản, hãy chuyển sang khám phá các tính năng mạnh mẽ của nó.

Chương 2: Các lệnh và tính năng cốt lõi

Chương này bao gồm các lệnh cốt lõi của Redocly CLI. Chúng tôi sẽ khám phá cách lint, quản lý, tạo tài liệu và phân tích định nghĩa API của bạn. Đối với các ví dụ trong chương này, chúng tôi sẽ sử dụng một tệp openapi.yaml đơn giản.

Hãy tạo một tệp có tên openapi.yaml với nội dung sau:

openapi: 3.0.0
info:
  title: Simple Pet Store API
  version: 1.0.0
  description: A simple API to manage pets.
servers:
  - url: <http://localhost:8080/api>
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      responses:
        '200':
          description: An array of pets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string

Mục 2.1: Linting mô tả API của bạn (lint)

Linting API là quy trình kiểm tra tệp định nghĩa API của bạn về tính nhất quán, tính chính xác và phong cách. Nó giúp bạn thực thi các hướng dẫn thiết kế API và phát hiện các vấn đề tiềm ẩn trước khi chúng được đưa vào sản xuất.

Cách sử dụng cơ bản

Lệnh lint được sử dụng để kiểm tra định nghĩa API của bạn dựa trên một bộ quy tắc.

redocly lint openapi.yaml

Theo mặc định, redocly lint sử dụng bộ quy tắc recommended. Nếu tệp openapi.yaml của chúng ta có vấn đề, đầu ra sẽ chi tiết chúng. Đối với tệp ví dụ của chúng ta, đầu ra sẽ là:

validating openapi.yaml...
openapi.yaml: validated in 58ms

Woohoo! Your API description is valid. 🎉

Cấu hình quy tắc

Redocly CLI đi kèm với ba bộ quy tắc có thể cấu hình được tích hợp sẵn:

Bạn có thể chỉ định một bộ quy tắc bằng tùy chọn --extends:

redocly lint openapi.yaml --extends=minimal

Bạn cũng có thể tạo bộ quy tắc tùy chỉnh của riêng mình trong tệp cấu hình redocly.yaml. Chúng tôi sẽ đề cập đến điều này trong Chương 3.

Định dạng đầu ra

Lệnh lint hỗ trợ nhiều định dạng đầu ra khác nhau bằng cách sử dụng tùy chọn --format, rất hữu ích cho việc tích hợp với các công cụ khác.

Ví dụ về việc sử dụng định dạng stylish:

redocly lint openapi.yaml --format=stylish

Bỏ qua vấn đề

Đôi khi bạn có thể cần bỏ qua một vấn đề cụ thể. Bạn có thể tạo một tệp .redocly.lint-ignore.yaml để chặn lỗi và cảnh báo.

redocly lint openapi.yaml --generate-ignore-file

Lệnh này sẽ tạo một tệp bỏ qua. Nếu bạn chạy lint lần nữa, các vấn đề được liệt kê trong tệp này sẽ bị bỏ qua. Điều này cho phép bạn kiểm soát chi tiết quy trình linting.

Mục 2.2: Quản lý mô tả API với bundle và split

Khi API của bạn phát triển, việc quản lý một tệp OpenAPI đơn lẻ, nguyên khối trở nên cồng kềnh. Redocly CLI cung cấp hai lệnh để giúp giải quyết vấn đề này: split và bundle.

Chia tệp OpenAPI lớn (split)

Lệnh split cho phép bạn chia nhỏ một tệp định nghĩa API lớn thành cấu trúc đa tệp dễ quản lý hơn. Nó trích xuất các thành phần, đường dẫn và ví dụ vào các tệp và thư mục riêng biệt.

Hãy chia tệp openapi.yaml của chúng ta:

redocly split openapi.yaml --outDir=split-api

Lệnh này sẽ tạo một thư mục split-api với cấu trúc sau:

split-api/
├── components/
│   └── schemas/
│       └── Pet.yaml
├── paths/
│   └── pets.yaml
└── openapi.yaml

Tệp openapi.yaml mới trong split-api bây giờ sẽ sử dụng $ref để liên kết đến các tệp bên ngoài:

# split-api/openapi.yaml
openapi: 3.0.0
info:
  title: Simple Pet Store API
# ...
paths:
  /pets:
    $ref: ./paths/pets.yaml
components:
  schemas:
    Pet:
      $ref: ./components/schemas/Pet.yaml

Điều này giúp việc quản lý các phần khác nhau của API của bạn dễ dàng hơn nhiều.

Gộp nhiều tệp (bundle)

Lệnh bundle làm ngược lại với split. Nó lấy một tệp định nghĩa API gốc và giải quyết tất cả các $ref cục bộ để tạo ra một tệp đơn lẻ, tự chứa. Điều này hữu ích cho các công cụ không hỗ trợ định nghĩa đa tệp.

Hãy gộp API đã chia của chúng ta trở lại thành một tệp duy nhất:

redocly bundle split-api/openapi.yaml --output bundled-api.yaml

Tệp bundled-api.yaml sẽ có nội dung giống như tệp openapi.yaml gốc của chúng ta.

Dereferencing

Lệnh bundle cũng có thể tạo một tệp đã được dereference hoàn toàn, trong đó tất cả các $ref (bao gồm cả các tham chiếu từ xa) được giải quyết và thay thế bằng nội dung của chúng.

redocly bundle split-api/openapi.yaml --output dereferenced-api.yaml --dereferenced

Điều này có thể hữu ích, nhưng hãy lưu ý rằng nó có thể làm cho tệp lớn hơn nhiều và các tham chiếu vòng có thể gây ra sự cố với đầu ra JSON.

Mục 2.3: Tạo tài liệu API (build-docs)

Một trong những tính năng mạnh mẽ nhất của Redocly CLI là khả năng tạo tài liệu tham khảo API đẹp mắt, tương tác bằng cách sử dụng công cụ Redoc mã nguồn mở.

Cách sử dụng cơ bản

Để tạo tài liệu, sử dụng lệnh build-docs:

redocly build-docs openapi.yaml

Điều này sẽ tạo một tệp redoc-static.html trong thư mục hiện tại của bạn. Mở nó trong trình duyệt để xem tài liệu của bạn.

Bạn có thể chỉ định một tệp đầu ra khác bằng tùy chọn -o hoặc --output:

redocly build-docs openapi.yaml -o my-api-docs.html

Tùy chỉnh đầu ra

Bạn có thể tùy chỉnh giao diện tài liệu của mình bằng cách sử dụng tùy chọn --theme.openapi. Điều này cho phép bạn thay đổi màu sắc, phông chữ và thậm chí vô hiệu hóa các phần của giao diện người dùng như thanh tìm kiếm.

Ví dụ, để vô hiệu hóa thanh tìm kiếm:

redocly build-docs openapi.yaml --theme.openapi.disableSearch

Bạn có thể tìm thấy tất cả các tùy chọn chủ đề có sẵn trong tài liệu chính thức của Redocly.

Để kiểm soát nhiều hơn nữa, bạn có thể cung cấp mẫu Handlebars của riêng mình để hiển thị tài liệu. Đây là một tính năng nâng cao cho phép tùy chỉnh hoàn toàn đầu ra HTML.

Mục 2.4: Lấy số liệu thống kê API (stats)

Lệnh stats cung cấp các số liệu hữu ích về định nghĩa API của bạn, chẳng hạn như số lượng đường dẫn, hoạt động, lược đồ và hơn thế nữa.

Cách lấy số liệu thống kê

Để lấy số liệu thống kê cho API của bạn, chỉ cần chạy:

redocly stats openapi.yaml

Đầu ra mặc định ở định dạng stylish:

Document: openapi.yaml stats:

🚗 References: 1
📦 External Documents: 0
📈 Schemas: 1
👉 Parameters: 0
🔗 Links: 0
🔀 Path Items: 1
👷 Operations: 1
🔖 Tags: 0

openapi.yaml: stats processed in 22ms

Các định dạng khác nhau

Giống như lệnh lint, stats hỗ trợ các định dạng đầu ra khác nhau với tùy chọn --format. Các định dạng json và markdown đặc biệt hữu ích.

redocly stats openapi.yaml --format=json

Điều này rất tốt để đưa số liệu thống kê vào các công cụ hoặc bảng điều khiển khác.

redocly stats openapi.yaml --format=markdown

Điều này tạo ra một bảng Markdown, hoàn hảo cho báo cáo hoặc để sử dụng trong các tóm tắt của GitHub Actions, như chúng ta sẽ thấy trong chương tiếp theo.

Chương 3: Các chủ đề nâng cao

Trong chương này, chúng ta sẽ đi sâu vào một số tính năng nâng cao hơn của Redocly CLI, bao gồm tệp cấu hình mạnh mẽ và tích hợp với các pipeline CI/CD.

Tệp cấu hình (redocly.yaml)

Trong khi bạn có thể sử dụng Redocly CLI hoàn toàn từ dòng lệnh, tệp cấu hình redocly.yaml cho phép bạn lưu trữ cấu hình của mình ở một nơi, giúp các lệnh của bạn ngắn hơn và cấu hình của bạn có thể tái sử dụng.

Hãy tạo một tệp redocly.yaml ở thư mục gốc của dự án của chúng ta:

# redocly.yaml

# This is a sample configuration file.
# For a full list of options, see the Redocly documentation.

apis:
  main:
    root: openapi.yaml

lint:
  extends:
    - recommended
  rules:
    # You can customize rules here.
    # For example, make sure all operations have a summary.
    operation-summary: error

Cấu trúc của tệp cấu hình

Sử dụng bí danh API

Với phần apis đã được cấu hình, bây giờ bạn có thể sử dụng bí danh main thay vì đường dẫn tệp trong các lệnh của mình:

redocly lint main
redocly stats main
redocly build-docs main

Điều này đặc biệt hữu ích khi bạn có nhiều API trong dự án của mình. Nếu bạn chạy redocly lint mà không có đối số nào, nó sẽ lint tất cả các API được định nghĩa trong phần apis.

Tích hợp liên tục (CI)

Tích hợp Redocly CLI vào pipeline CI/CD của bạn là một cách tuyệt vời để tự động hóa kiểm tra chất lượng API. Dưới đây là ví dụ về cách sử dụng nó với GitHub Actions.

Tạo một tệp có tên .github/workflows/redocly.yaml:

name: Redocly CLI Checks

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  lint-and-stats:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'

      - name: Install Redocly CLI
        run: npm install -g @redocly/cli@latest

      - name: Lint API definition
        run: redocly lint openapi.yaml --format=github-actions

      - name: Get API stats
        run: redocly stats openapi.yaml --format=markdown >> $GITHUB_STEP_SUMMARY

Quy trình làm việc GitHub Actions này thực hiện những điều sau:

  1. Nó kích hoạt trên mỗi lần push và pull request đến nhánh main.
  2. Nó checkout mã của bạn.
  3. Nó cài đặt Node.js và Redocly CLI.
  4. Nó chạy lệnh lint với định dạng github-actions. Điều này sẽ tự động chú thích bất kỳ vấn đề nào trực tiếp trong pull request của bạn.
  5. Nó chạy lệnh stats với định dạng markdown và thêm đầu ra vào tóm tắt công việc, cung cấp cho bạn một báo cáo đẹp mắt trên mỗi lần chạy.

Đây là một cách mạnh mẽ để đảm bảo rằng định nghĩa API của bạn luôn ở trạng thái tốt.

Chương 4: Ví dụ thực tế: Một quy trình làm việc hoàn chỉnh

Trong chương cuối cùng này, chúng ta sẽ kết hợp mọi thứ đã học và đi qua một quy trình làm việc hoàn chỉnh, thực tế. Chúng ta sẽ:

  1. Tạo cấu trúc dự án với định nghĩa API đa tệp.
  2. Tạo tệp cấu hình redocly.yaml.
  3. Lint định nghĩa API bằng cấu hình tùy chỉnh của chúng ta.
  4. Gộp API thành một tệp duy nhất.
  5. Tạo tài liệu API.

1. Thiết lập dự án

Hãy tạo một thư mục mới cho dự án của chúng ta và thiết lập cấu trúc tệp.

mkdir redocly-petstore
cd redocly-petstore
mkdir -p openapi/components/schemas openapi/paths

Bây giờ, hãy tạo các tệp API đã chia.

openapi/components/schemas/Pet.yaml:

type: object
properties:
  id:
    type: integer
    format: int64
  name:
    type: string
  tag:
    type: string

openapi/paths/pets.yaml:

get:
  summary: List all pets
  operationId: listPets
  responses:
    '200':
      description: An array of pets.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: ../components/schemas/Pet.yaml

openapi/root.yaml (điểm vào chính của chúng ta):

openapi: 3.0.0
info:
  title: Petstore API
  version: 1.0.0
  description: A professional API for managing pets.
servers:
  - url: <https://api.petstore.com/v1>
paths:
  /pets:
    $ref: ./paths/pets.yaml

2. Tạo redocly.yaml

Bây giờ, hãy tạo tệp cấu hình của chúng ta ở thư mục gốc của thư mục redocly-petstore.

redocly.yaml:

apis:
  petstore@v1:
    root: openapi/root.yaml

lint:
  extends:
    - recommended
  rules:
    operation-summary: error
    no-path-trailing-slash: warn
    tag-description: error

Trong cấu hình này, chúng ta đã định nghĩa một bí danh petstore@v1 cho API của chúng ta và thêm một số quy tắc linting tùy chỉnh.

3. Lint API

Bây giờ, hãy lint API của chúng ta bằng cấu hình mới.

redocly lint petstore@v1

Bạn sẽ thấy một số lỗi và cảnh báo vì API của chúng ta chưa tuân thủ tất cả các quy tắc mới. Ví dụ, chúng ta chưa có các thẻ với mô tả. Điều này minh họa cách bạn có thể thực thi hướng dẫn kiểu API của riêng mình.

4. Gộp API

Tiếp theo, hãy gộp API đa tệp của chúng ta thành một tệp phân phối duy nhất.

redocly bundle petstore@v1 -o dist/petstore.yaml

Điều này sẽ tạo một thư mục dist với tệp petstore.yaml bên trong, chứa định nghĩa API đã được giải quyết hoàn toàn.

5. Tạo tài liệu

Cuối cùng, hãy tạo tài liệu API của chúng ta.

redocly build-docs petstore@v1 -o dist/petstore-docs.html

Điều này sẽ tạo dist/petstore-docs.html. Mở tệp này trong trình duyệt để xem tài liệu API đẹp mắt, tương tác của bạn.

Và thế là xong! Một quy trình làm việc hoàn chỉnh từ định nghĩa API đa tệp, có cấu trúc đến tệp đã gộp và tài liệu chuyên nghiệp, tất cả được quản lý bằng Redocly CLI.

Kết luận

Trong hướng dẫn này, chúng ta đã đi sâu vào Redocly CLI. Chúng ta bắt đầu với những điều cơ bản về cài đặt và các lệnh cốt lõi, sau đó chuyển sang các chủ đề nâng cao như cấu hình và tích hợp CI, và cuối cùng là đi qua một quy trình làm việc hoàn chỉnh, thực tế.

Bây giờ bạn nên hiểu rõ cách sử dụng Redocly CLI để:

Redocly CLI là một công cụ linh hoạt và mạnh mẽ có thể cải thiện đáng kể quy trình phát triển API của bạn. Tôi khuyến khích bạn khám phá thêm các tính năng của nó và tích hợp nó vào các dự án của mình.

Tài nguyên bổ sung

Cảm ơn bạn đã theo dõi hướng dẫn này. Chúc bạn xây dựng API thành công!

💡
Bạn muốn một công cụ Kiểm tra API tuyệt vời tạo ra Tài liệu API đẹp mắt?

Bạn muốn một nền tảng tích hợp, Tất cả trong một để Nhóm phát triển của bạn làm việc cùng nhau với năng suất tối đa?

Apidog đáp ứng mọi yêu cầu của bạn và thay thế Postman với mức giá phải chăng hơn nhiều!
button

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API

Đăng ký miễn phíTải xuống