Blog

Cách Chuyển Đổi Bộ Sưu Tập Postman Sang OpenAPI 3.0: Hướng Dẫn Từng Bước

Cách tốt nhất để chuyển đổi bộ sưu tập postman sang định dạng OpenAI 3.0 là gì? Bài viết này phác thảo 3 tùy chọn hàng đầu, hãy xem qua!

Minh Triết

Minh Triết

3 tháng 6 2025

Cách Chuyển Đổi Bộ Sưu Tập Postman Sang OpenAPI 3.0: Hướng Dẫn Từng Bước
button

Là một nhà phát triển làm việc với APIs, có lẽ bạn không còn xa lạ gì với Postman, một công cụ phổ biến để kiểm tra và tài liệu hóa các điểm cuối của bạn. Tuy nhiên, khi chia sẻ tài liệu API của bạn ở định dạng chuẩn như OpenAPI 3.0, bạn có thể sẽ cảm thấy bối rối.

Đừng lo! Hướng dẫn toàn diện này sẽ hướng dẫn bạn qua quy trình chuyển đổi các bộ sưu tập Postman của bạn thành các thông số OpenAPI 3.0, với sự tập trung vào gói npm phổ biến postman-to-openapi.

Tại sao lại chuyển đổi Postman sang OpenAPI?

Trước khi bắt đầu, hãy nhanh chóng đề cập đến lý do bạn có thể muốn chuyển đổi các bộ sưu tập Postman của mình thành OpenAPI:

Bây giờ, hãy khám phá cách thực hiện sự chuyển đổi này!

Sử dụng postman-to-openapi: Hướng dẫn từng bước

Gói npm postman-to-openapi là một công cụ mạnh mẽ để chuyển đổi các bộ sưu tập Postman thành các thông số OpenAPI 3.0. Dưới đây là hướng dẫn từng bước về cách sử dụng nó:

Bước 1: Cài đặt gói postman-to-openai qua npm

Đầu tiên, bạn cần cài đặt gói này. Mở terminal của bạn và chạy:

npm install postman-to-openapi

Hoặc nếu bạn thích yarn:

yarn add postman-to-openapi

Bước 2: Sử dụng postman-to-openai trong Node.js

Sau khi cài đặt, bạn có thể sử dụng gói này trong dự án Node.js của mình. Đây là một ví dụ đơn giản:

const postmanToOpenApi = require('postman-to-openapi')

const postmanCollection = './path/to/your/collection.json'
const outputFile = './output/openapi.yml'

async function convertCollection() {
  try {
    const result = await postmanToOpenApi(postmanCollection, outputFile, {
      defaultTag: 'General'
    })
    console.log(`OpenAPI specs: ${result}`)
  } catch (err) {
    console.error('Chuyển đổi không thành công:', err)
  }
}

convertCollection()

Đoạn mã này sẽ chuyển đổi bộ sưu tập Postman của bạn thành một tệp YAML OpenAPI 3.0.

Bước 3: Cách sử dụng tùy chỉnh postman-to-openai

Gói postman-to-openapi cung cấp nhiều tùy chọn để tùy chỉnh việc chuyển đổi của bạn. Dưới đây là một số tùy chọn hữu ích:

Hãy sửa đổi đoạn mã của chúng ta để sử dụng những tùy chọn này:

const postmanToOpenApi = require('postman-to-openapi')

const postmanCollection = './path/to/your/collection.json'
const outputFile = './output/openapi.json'

async function convertCollection() {
  try {
    const result = await postmanToOpenApi(postmanCollection, outputFile, {
      defaultTag: 'MyAPI',
      outputFormat: 'json',
      includeAuthInfoInExample: true
    })
    console.log(`OpenAPI specs: ${result}`)
  } catch (err) {
    console.error('Chuyển đổi không thành công:', err)
  }
}

convertCollection()

Đoạn mã này sẽ xuất một tệp JSON với thông tin xác thực được bao gồm trong các ví dụ và tất cả các hoạt động được gán thẻ là 'MyAPI'.

Nếu tôi không muốn sử dụng gói postman-to-openai thì sao?

Mặc dù gói postman-to-openapi rất tốt cho việc chuyển đổi đơn giản, đôi khi bạn có thể cần nhiều quyền kiểm soát hơn hoặc có yêu cầu cụ thể. Hãy cùng khám phá một số kỹ thuật nâng cao.

Tùy chọn 1. Sử dụng APIDog để chuyển đổi Postman sang OpenAPI

APIDog là một công cụ tuyệt vời khác có thể giúp bạn chuyển đổi các bộ sưu tập Postman thành định dạng OpenAPI. Dưới đây là hướng dẫn nhanh về cách sử dụng nó:

  1. Đăng nhập vào APIDog và điều hướng đến menu "Cài đặt".
  2. Chọn "Nhập khẩu" từ các tùy chọn.
  3. Chọn tệp bộ sưu tập Postman mà bạn muốn nhập khẩu. APIDog sẽ nhập và chuyển đổi bộ sưu tập của bạn, cho phép bạn xem và chỉnh sửa tài liệu API kết quả.
Chuyển đổi Postman sang định dạng OpenAPI 3.0: Nhập bộ sưu tập Postman của bạn vào APIDog
Nhập bộ sưu tập Postman của bạn vào APIDog 

4. Nhấp vào nút Xuất Dữ liệu, và chọn xuất sang định dạng OpenAPI 3.0.

Chuyển đổi Postman sang định dạng OpenAPI 3.0
Xuất dữ liệu Postman của bạn sang định dạng OpenAPI 3.0

Nhưng khoan đã, APIDog không chỉ là một công cụ chuyển đổi cho các bộ sưu tập Postman sang định dạng OpenAPI. Nó là một lựa chọn dễ sử dụng giúp bạn quên đi việc phải trả tiền cho Postman Enterprise.

APIDog cung cấp các tính năng bổ sung như kiểm tra API và máy chủ giả, giúp nó trở thành một giải pháp toàn diện cho phát triển và tài liệu API. Đây là những gì bạn nhận được từ APIDog thay vì đăng ký Postman với giá 19 đô la/tháng:

Tất cả đều có sẵn trong Phiên bản Miễn phí APIDog!

Hơn nữa, chỉ với 9 đô la/tháng, bạn có thể truy cập tất cả các tính năng cho Kế hoạch Chuyên nghiệp của Postman mà sẽ tốn của bạn 39 đô la/tháng!

button

Tùy chọn 2. Sử dụng API Postman để chuyển đổi

Postman tự nó cung cấp một API có thể chuyển đổi các bộ sưu tập sang định dạng OpenAPI. Đây là cách bạn có thể sử dụng nó:

  1. Lấy khóa API Postman của bạn từ cài đặt tài khoản của bạn.
  2. Sử dụng lệnh curl sau (thay thế các giá trị giữ chỗ bằng các giá trị thực tế của bạn):
curl --location --request GET 'https://api.getpostman.com/collections/{{collectionId}}/transformations' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {{postman-api-key}}'
  1. Phản hồi sẽ chứa thông số OpenAPI. Bạn có thể lưu điều này vào một tệp để sử dụng sau này.

Tùy chọn 3. Công cụ trực tuyến cho chuyển đổi Postman sang OpenAPI

Nếu bạn thích một giải pháp nhanh chóng, không cần mã hóa, bạn có thể sử dụng một số công cụ trực tuyến giúp chuyển đổi nhanh chóng. Đây là cách sử dụng nó:

  1. Chọn từ một trong các công cụ trực tuyến miễn phí có sẵn.
  2. Tải tệp JSON bộ sưu tập Postman của bạn lên hoặc dán URL bộ sưu tập.
  3. Nhấp vào "Chuyển đổi" và tải xuống thông số OpenAPI kết quả.

Phương pháp này rất tốt cho việc chuyển đổi một lần hoặc khi bạn không muốn thiết lập môi trường phát triển.

Cách chuyển đổi Postman sang OpenAPI mà không gặp rắc rối: Mẹo và thực tiễn tốt nhất

Ngay cả với các công cụ tốt nhất, bạn có thể gặp phải một số trục trặc. Dưới đây là một số vấn đề thường gặp và giải pháp của chúng:

Vì vậy, để đảm bảo quy trình chuyển đổi diễn ra suôn sẻ, hãy ghi nhớ những mẹo này:

Kết luận

Chuyển đổi các bộ sưu tập Postman thành các thông số OpenAPI là một bước quan trọng trong việc chuẩn hóa tài liệu API và đảm bảo tích hợp mượt mà với các hệ thống khác.

Bằng cách làm theo các bước được nêu trong hướng dẫn này, bạn có thể chuyển đổi hiệu quả các bộ sưu tập Postman của mình và tận dụng những lợi ích mà OpenAPI mang lại.

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

H: Lợi ích chính của việc chuyển đổi các bộ sưu tập Postman thành các thông số OpenAPI là gì?
Đ: Lợi ích chính là chuẩn hóa, giúp dễ dàng tích hợp với các hệ thống và công cụ khác.

H: Tôi có thể sử dụng các công cụ trực tuyến cho việc chuyển đổi Postman sang OpenAPI không?
Đ: Có, các công cụ trực tuyến như p2o.defcon007.com và APIDog có sẵn để chuyển đổi các bộ sưu tập Postman sang các thông số OpenAPI.

H: Làm thế nào tôi xử lý các bộ sưu tập Postman lớn trong quá trình chuyển đổi?
Đ: Các bộ sưu tập lớn có thể được chia thành các phần nhỏ hơn, tổ chức bằng cách sử dụng các thư mục, hoặc được chuyển đổi bằng các công cụ như Bộ chuyển đổi API.

H: Có cần xác thực thông số OpenAPI sau khi chuyển đổi không?
Đ: Có, xác thực thông số OpenAPI sau khi chuyển đổi là rất quan trọng để đảm bảo nó chính xác và đầy đủ.

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