tessl/npm-oas-normalize

Tooling for converting, validating, and parsing OpenAPI, Swagger, and Postman API definitions

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Format Conversion

Name: tessl/npm-oas-normalize
Author: tessl

Automatic conversion capabilities for transforming Swagger 2.0 and Postman collections to OpenAPI 3.x format, ensuring consistent output regardless of input format.

Capabilities

Convert Method

Convert any supported API definition format to OpenAPI 3.x, with automatic detection and transformation of Swagger 2.0 and Postman collections.

/**
 * Convert a given API definition to OpenAPI format if it is not already
 * Handles Swagger 2.0 to OpenAPI 3.x conversion and Postman to OpenAPI conversion
 * @returns Promise resolving to OpenAPI document
 */
async convert(): Promise<OpenAPI.Document>;

Usage Examples:

import OASNormalize from "oas-normalize";

// Convert Swagger 2.0 to OpenAPI 3.x
const swagger20Spec = {
  swagger: "2.0",
  info: { title: "Pet Store", version: "1.0.0" },
  host: "petstore.swagger.io",
  basePath: "/v2",
  schemes: ["https"],
  paths: {
    "/pets": {
      get: {
        summary: "List pets",
        responses: {
          "200": {
            description: "Successful response"
          }
        }
      }
    }
  }
};

const oas = new OASNormalize(swagger20Spec);
const openapi = await oas.convert();

console.log(openapi.openapi); // "3.0.3" (or similar)
console.log(openapi.servers); // [{ url: "https://petstore.swagger.io/v2" }]

// Convert Postman collection to OpenAPI
const postmanCollection = {
  info: {
    name: "Pet Store API",
    schema: "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  item: [
    {
      name: "Get Pets",
      request: {
        method: "GET",
        url: "{{baseUrl}}/pets"
      }
    }
  ]
};

const oasPostman = new OASNormalize(postmanCollection);
const openapi = await oasPostman.convert();

console.log(openapi.openapi); // "3.0.0"
console.log(openapi.info.title); // Derived from Postman collection

// OpenAPI definitions pass through unchanged
const openapi31Spec = {
  openapi: "3.1.0",
  info: { title: "Already OpenAPI", version: "1.0.0" },
  paths: {}
};

const oasAlready = new OASNormalize(openapi31Spec);
const result = await oasAlready.convert();
// Returns the same object (no conversion needed)

Supported Source Formats

Swagger 2.0

Converts Swagger 2.0 specifications to OpenAPI 3.x format using the swagger2openapi library:

// Input: Swagger 2.0
const swagger = {
  swagger: "2.0",
  info: { title: "API", version: "1.0" },
  host: "api.example.com",
  basePath: "/v1",
  schemes: ["https"],
  definitions: {
    Pet: {
      type: "object",
      properties: {
        name: { type: "string" }
      }
    }
  },
  paths: {
    "/pets": {
      get: {
        responses: {
          "200": {
            description: "Success",
            schema: { $ref: "#/definitions/Pet" }
          }
        }
      }
    }
  }
};

// Output: OpenAPI 3.x equivalent
const converted = await new OASNormalize(swagger).convert();
// Results in:
// - openapi: "3.0.3"
// - servers: [{ url: "https://api.example.com/v1" }]
// - components.schemas.Pet (moved from definitions)
// - Updated response schema references

Key Swagger 2.0 Conversion Features:

Host + basePath + schemes → servers array
definitions → components.schemas
parameters → components.parameters (when referenced)
responses → components.responses (when referenced)
securityDefinitions → components.securitySchemes
Schema references updated to new format

Postman Collections

Converts Postman Collections (v2.0/v2.1) to OpenAPI format using @readme/postman-to-openapi:

// Input: Postman Collection
const postmanCollection = {
  info: {
    name: "My API",
    schema: "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  variable: [
    { key: "baseUrl", value: "https://api.example.com" }
  ],
  item: [
    {
      name: "Create User",
      request: {
        method: "POST",
        url: "{{baseUrl}}/users",
        header: [
          { key: "Content-Type", value: "application/json" }
        ],
        body: {
          mode: "raw",
          raw: '{"name": "John", "email": "john@example.com"}'
        }
      }
    }
  ]
};

const converted = await new OASNormalize(postmanCollection).convert();
// Results in OpenAPI 3.x with:
// - Inferred schemas from request/response examples
// - Authentication schemes from Postman auth settings
// - Path parameters from URL templates

Key Postman Conversion Features:

Request/response examples → schema inference
Postman variables → server variables or examples
Authentication settings → security schemes
Folder structure → OpenAPI tags
Pre-request scripts and tests → ignored (not applicable)

OpenAPI (Pass-through)

OpenAPI 3.x specifications are returned unchanged:

const openapi = {
  openapi: "3.1.0",
  info: { title: "Already OpenAPI" },
  paths: {}
};

const result = await new OASNormalize(openapi).convert();
// Returns identical object - no conversion performed

Error Handling

Unsupported Formats

const unsupportedSpec = {
  // Missing swagger, openapi, or Postman collection indicators
  info: { title: "Unknown format" }
};

try {
  await new OASNormalize(unsupportedSpec).convert();
} catch (error) {
  console.error(error.message); // "The supplied API definition is unsupported."
}

Swagger v1.2 Rejection

const swagger12 = {
  swagger: "1.2",
  info: { title: "Old Swagger" }
};

try {
  await new OASNormalize(swagger12).convert();
} catch (error) {
  console.error(error.message); // "Swagger v1.2 is unsupported."
}

Integration with Other Methods

The convert method works seamlessly with other OASNormalize methods:

const swagger = { swagger: "2.0", /* ... */ };
const oas = new OASNormalize(swagger);

// Convert, then validate the result
const openapi = await oas.convert();
await new OASNormalize(openapi).validate();

// Or validate the converted result directly
await oas.validate(); // Internally converts first if needed

Conversion Options

The conversion process uses default settings optimized for compatibility:

Swagger conversion: Uses swagger2openapi with anchors enabled for better $ref handling
Postman conversion: Uses JSON output format with variable replacement enabled
No Caching: Unlike other methods, convert() does not cache results and will perform conversion on each call

// The conversion is NOT cached - each call performs the conversion
const oas = new OASNormalize(swaggerSpec);
const first = await oas.convert();   // Performs conversion
const second = await oas.convert();  // Performs conversion again
console.log(first === second); // false (different object instances)

Install with Tessl CLI