Trong quy trình phát triển API hiện đại, việc tách biệt giữa công cụ tài liệu và công cụ kiểm thử thường làm giảm hiệu suất phối hợp của nhóm. Bài viết này sẽ giải thích cách sử dụng Redoc để tạo tài liệu API chuẩn và tích hợp liền mạch với Postman, giúp tự động hóa từ tài liệu đến kiểm thử.

Căn bản về tài liệu Redoc

Redoc là một công cụ render theo chuẩn OpenAPI, chuyển đổi định nghĩa API ở dạng YAML/JSON thành tài liệu tương tác. Điểm mạnh chính là khả năng triển khai không phụ thuộc và tính tùy biến cao.

Khởi chạy dịch vụ Redoc

Để xây dựng trang tài liệu tĩnh bằng Redocly CLI, trước tiên cài đặt công cụ toàn cầu qua npm:

npm install -g @redocly/cli

Tiếp theo, thực thi lệnh sau để tạo file HTML tài liệu:

redocly build-docs spec/openapi.yaml -o api-documentation.html

Lệnh trên sẽ chuyển file định nghĩa spec/openapi.yaml thành một trang HTML độc lập chứa danh mục API đầy đủ, mô tả tham số yêu cầu và ví dụ phản hồi.

Tùy chỉnh giao diện tài liệu

Redoc cung cấp nhiều tùy chọn cấu hình để đáp ứng nhu cầu doanh nghiệp. Ví dụ, bạn có thể ép các tham số bắt buộc hiển thị đầu tiên bằng cách sửa thuộc tính thẻ HTML:

<redoc spec-url="openapi.yaml" required-props-first="true"></redoc>

Ngoài ra, bạn cũng có thể điều chỉnh màu sắc thanh bên bằng cách sử dụng tùy chọn theme:

<redoc spec-url="openapi.yaml" theme='{"sidebar": {"backgroundColor": "#f5f5f5"}}'></redoc>

Các tùy chọn cấu hình chi tiết được liệt kê trong tài liệu chính thức.

Lưu chuyển hai chiều của định nghĩa API

File định nghĩa OpenAPI đóng vai trò cầu nối giữa Redoc và Postman, đảm bảo sự hợp tác mượt mà giữa hai công cụ.

Xuất định nghĩa OpenAPI từ Redoc

Tài liệu được tạo bởi Redoc thường kèm nút "Download" để người dùng lấy file định nghĩa gốc. Nếu muốn ẩn nút này, bạn có thể cấu hình như sau:

<redoc spec-url="openapi.yaml" hide-download-button="true"></redoc>

Dù ẩn đi, quản trị viên vẫn có thể truy cập trực tiếp đường dẫn file định nghĩa để lấy phiên bản mới nhất.

Nhập định nghĩa OpenAPI vào Postman

Postman hỗ trợ nhập trực tiếp file định nghĩa OpenAPI để tạo tập kiểm thử hoàn chỉnh. Chọn "Import" → "File", chọn file YAML/JSON xuất từ Redoc, hệ thống sẽ tự động phân tích và tạo tập chứa tất cả các điểm cuối (endpoints).

Kỹ thuật tích hợp nâng cao

Bằng cách kết hợp mở rộng Redoc và biến môi trường Postman, bạn có thể đạt được sự tích hợp sâu hơn.

Tăng cường dữ liệu kiểm thử với mở rộng Redoc

Bạn có thể thêm mẫu mã nguồn đa ngôn ngữ bằng cách sử dụng mở rộng x-codeSamples. Ví dụ:

x-codeSamples:
  - lang: Python
    source: |
      import requests
      response = requests.post('/api/users', json={'name': 'test'})
      print(response.json())

Mẫu mã này sẽ hiển thị trong tài liệu Redoc và có thể được sao chép trực tiếp vào Pre-request Script của Postman.

Đồng bộ biến môi trường

Biến môi trường Postman có thể liên kết với URL máy chủ được định nghĩa trong tài liệu Redoc. Ví dụ, cấu hình server trong định nghĩa:

servers:
  - url: https://api.production.com/v1
    description: Môi trường sản xuất
  - url: https://api.test.com/v1
    description: Môi trường thử nghiệm

Người dùng chọn máy chủ trong tài liệu Redoc, sau đó đồng bộ giá trị này tới biến môi trường Postman thông qua script tùy chỉnh.

Kiểm thử tự động và tích hợp liên tục

Kết hợp Redoc và Postman vào quy trình CI/CD có thể đảm bảo tài liệu và kiểm thử luôn đồng bộ. Newman, công cụ dòng lệnh của Postman, cho phép chạy tập kiểm thử hàng loạt:

newman run collection.json -e environment.json

Với GitLab CI/CD hoặc GitHub Actions, bạn có thể kích hoạt tự động khi định nghĩa API thay đổi:

# .github/workflows/api-test.yml
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm install -g newman
      - run: newman run spec/openapi.yaml -e env/test.json

Giải quyết vấn đề thường gặp

Trong quá trình tích hợp, bạn có thể gặp phải các vấn đề như không tương thích phiên bản định nghĩa hoặc xung đột tham số.

Xử lý khác biệt phiên bản OpenAPI

Khi xảy ra lỗi khi nhập định nghĩa phiên bản cao, bạn có thể chuyển đổi xuống phiên bản thấp hơn bằng Redocly CLI:

redocly lint openapi.yaml --format=json --max-problems=0

Lệnh này sẽ kiểm tra và cung cấp đề xuất sửa chữa để đảm bảo tính tương thích.

Giải quyết xung đột tên tham số

Nếu có tham số cùng tên (ví dụ, tham số đường dẫn và truy vấn), bạn có thể loại trừ tạm thời bằng cách sử dụng mở rộng x-ignoredHeaderParameters.