@readme/postman-to-openapi

What is @readme/postman-to-openapi?

@readme/postman-to-openapi is an npm package that allows you to convert Postman collections to OpenAPI specifications. This is particularly useful for developers who want to document their APIs in a standardized format or migrate their API documentation from Postman to OpenAPI.

What are @readme/postman-to-openapi's main functionalities?

Convert Postman Collection to OpenAPI

This feature allows you to convert a Postman collection JSON file to an OpenAPI YAML file. You can specify options such as the default tag for the generated OpenAPI documentation.

const postmanToOpenApi = require('@readme/postman-to-openapi');

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

postmanToOpenApi(postmanCollection, outputFile, { defaultTag: 'General' })
  .then(result => {
    console.log(`OpenAPI specs written to: ${result}`);
  })
  .catch(err => {
    console.error(err);
  });

Convert Postman Collection to OpenAPI with Custom Options

This feature allows you to convert a Postman collection to an OpenAPI file with custom options such as title, version, and description for the API documentation.

const postmanToOpenApi = require('@readme/postman-to-openapi');

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

const options = {
  defaultTag: 'General',
  info: {
    title: 'My API',
    version: '1.0.0',
    description: 'This is a sample API'
  }
};

postmanToOpenApi(postmanCollection, outputFile, options)
  .then(result => {
    console.log(`OpenAPI specs written to: ${result}`);
  })
  .catch(err => {
    console.error(err);
  });

Other packages similar to @readme/postman-to-openapi

postman-to-swagger

postman-to-swagger is a package that converts Postman collections to Swagger (OpenAPI 2.0) specifications. While @readme/postman-to-openapi focuses on OpenAPI 3.0, postman-to-swagger is useful if you need to work with the older Swagger format.

postman-collection-transformer

postman-collection-transformer is a versatile package that allows you to convert Postman collections between different versions and formats, including OpenAPI. It offers more flexibility in terms of transformations but may require more configuration compared to @readme/postman-to-openapi.

README

@readme/postman-to-openapi

🛸 Convert Postman Collection v2.1/v2.0 to OpenAPI v3.0.

Or in other words, transform this specification and also this to this one

Installation

Using npm:

npm i @readme/postman-to-openapi

Using yarn:

yarn add @readme/postman-to-openapi

Quick Usage

As a library

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

// Postman collection
const postmanCollection = './path/to/postman/collection.json'
// Output OpenAPI Path
const outputFile = './api/collection.yml'

postmanToOpenAPI(postmanCollection, outputFile, { defaultTag: 'General' })
  .then(result => {
    console.log(`OpenAPI specs: ${result}`)
  })
  .catch(err => {
    console.log(err)
  })

Documentation

All features, usage instructions and help can be found in the Documentation page

Differences from postman-to-openapi

There are some small differences between this library and the postman-to-openapi upstream:

• Does not ship with a CLI component.
• Has protections in place to prevent undefined statuses from being set.
• Has no version property on the exported method to determine which version you're running as this is unnecessary without a CLI component.

Changelog

4.1.0 (2023-05-01)

• fix: create a response description if one is missing (#3) (b13f7e5), closes #3
• chore(deps-dev): bumping out of date deps (66f1f68)