Spec Transformer

Maintained by Mohammad Noor | Expedia Group

A composable pipeline for transforming OpenAPI 3.0 specifications.

• Strip unwanted HTTP headers before publishing API docs
• Prepend path prefixes for API gateway routing
• Consolidate tags for unified documentation portals
• Auto-generate oneOf discriminator patterns for polymorphic schemas
• Convert OpenAPI specs to Postman Collections

Available as a CLI and a TypeScript library.

Quick links: CLI Usage | Library Usage | Transformers | Examples

Architecture

Installation

npm install @expediagroup/spec-transformer

CLI Usage

npx @expediagroup/spec-transformer --help

Options

Flag	Description
--input [path]	Input file path
--inputFormat [value]	Input format: json or yaml (default: yaml)
--output [path]	Output file path
--outputFormat [value]	Output format: json or yaml (default: yaml, or json when --postman is used)
--headers [list]	Remove specified headers (comma-separated), or common headers if no value given
--tags [value]	Replace all tags with the given tag
--endpoint [prefix]	Prepend a path prefix, or auto-extract from the first server URL
--oneOf	Generate oneOf arrays for polymorphic schemas
--postman	Convert to Postman Collection format
--operationIdsToTags	Use operation IDs as tags
--defaultStringType [value]	YAML string quoting style: PLAIN (default) or QUOTE_SINGLE

Examples

# Remove common headers
npx @expediagroup/spec-transformer --input api.yaml --output clean.yaml --headers

# Remove specific headers
npx @expediagroup/spec-transformer --input api.yaml --output clean.yaml --headers "authorization,x-api-key"

# Chain transformations
npx @expediagroup/spec-transformer --input api.yaml --output out.yaml --headers --tags my-api --endpoint /v2

# Convert to Postman Collection
npx @expediagroup/spec-transformer --input api.yaml --output collection.json --postman

Library Usage

Single transformer

import {
  COMMON_UNWANTED_HEADERS,
  HeaderRemovalTransformer,
  TransformerChain,
  YamlReader,
  YamlWriter,
} from '@expediagroup/spec-transformer';

const specs = '...'; // OpenAPI spec as a YAML string

const chain = new TransformerChain([
  new HeaderRemovalTransformer(COMMON_UNWANTED_HEADERS),
]);

const result = chain.transform(specs, new YamlReader(), new YamlWriter());
console.log(result);

COMMON_UNWANTED_HEADERS removes: accept, accept-encoding, user-agent, authorization, content-type.

Chaining multiple transformers

import {
  COMMON_UNWANTED_HEADERS,
  EndpointTransformer,
  HeaderRemovalTransformer,
  TagsSettingTransformer,
  TransformerChain,
  YamlReader,
  YamlWriter,
} from '@expediagroup/spec-transformer';

const chain = new TransformerChain([
  new HeaderRemovalTransformer(COMMON_UNWANTED_HEADERS),
  new TagsSettingTransformer('my-api'),
  new EndpointTransformer('/v2'),
]);

const result = chain.transform(specs, new YamlReader(), new YamlWriter());

In-memory objects

Use transformRecord() when you already have a parsed spec object:

import {
  COMMON_UNWANTED_HEADERS,
  HeaderRemovalTransformer,
  TransformerChain,
} from '@expediagroup/spec-transformer';

const spec = { openapi: '3.0.0', paths: { /* ... */ } };

const chain = new TransformerChain([
  new HeaderRemovalTransformer(COMMON_UNWANTED_HEADERS),
]);

const result = chain.transformRecord(spec);

Transformers

Transformer	What it does
HeaderRemovalTransformer	Removes unwanted HTTP headers from operations and components. Resolves $ref references. Case-insensitive matching.
EndpointTransformer	Prepends a path prefix to all endpoints. Auto-extracts from the first server URL if omitted.
TagsSettingTransformer	Replaces all operation and top-level tags with a single target tag.
OperationIdsToTagsTransformer	Uses each operation's operationId as its tag.
OneOfSettingTransformer	Auto-generates oneOf arrays for polymorphic schema hierarchies using discriminator mappings.
PostmanTransformer	Converts an OpenAPI spec into a Postman Collection v2.1.

Before / After Examples

Header Removal

Three header parameters go in - only the custom one survives:

Before:

paths:
  /pets:
    get:
      parameters:
        - name: accept
          in: header
        - name: X-Request-ID
          in: header
        - name: content-type
          in: header

After (with COMMON_UNWANTED_HEADERS):

paths:
  /pets:
    get:
      parameters:
        - name: X-Request-ID
          in: header

OneOf Discriminator

A $ref pointing to a parent schema with a discriminator is replaced with a oneOf array of its leaf types:

Before:

paths:
  /test:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentMethod"

After (given PaymentMethod -> CreditCard, PayPal and CreditCard -> Visa, Mastercard hierarchies):

paths:
  /test:
    post:
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/PayPal"
                - $ref: "#/components/schemas/Mastercard"
                - $ref: "#/components/schemas/Debit"
                - $ref: "#/components/schemas/Credit"

Supported Formats

Format	Reader	Writer
YAML	YamlReader	YamlWriter
JSON	JsonReader	JsonWriter

Development

npm install
npm run build
npm test

Tests enforce a 90% coverage threshold across statements, branches, functions, and lines.

License

This project is licensed under the Apache License, Version 2.0.