Programmatic Usage

Use openapi-format as a Node.js module in your own scripts and tools.

Sorting with Minimal Setup

sort.js

const {
  parseFile,
  stringify,
  writeFile,
  openapiSort
} = require('openapi-format');

const input = await parseFile('spec.json'); // local path or remote URL
const { data } = await openapiSort(input, { sort: true });

const output = await stringify(data, { format: 'json' });
await writeFile('spec.sorted.json', output, { format: 'json' });

Custom Sort Configuration

custom-sort.js

const {
  parseFile,
  stringify,
  writeFile,
  openapiSort,
  getDefaultSortSet
} = require('openapi-format');

const document = await parseFile('spec.json');

const sortSet = await getDefaultSortSet();
sortSet.get = ['summary', 'description', 'responses']; // override GET priority

const { data } = await openapiSort(document, {
  sort: true,
  sortSet,
  sortComponentsSet: ['schemas', 'responses']
});

const output = await stringify(data, { format: 'json' });
await writeFile('spec.sorted.json', output, { format: 'json' });

Filtering & Generating

filter-generate.js

const {
  parseFile,
  openapiFilter,
  openapiGenerate
} = require('openapi-format');

let draft = await parseFile('spec.json');

// Filter by tags
draft = (await openapiFilter(draft, {
  filterSet: { tags: ['public'] }
})).data;

// Generate operationIds
draft = (await openapiGenerate(draft, {
  generateSet: {
    operationIdTemplate: '<method>_<pathPart1>_<pathPart2>'
  }
})).data;

File Helpers

The module exports smart parsing and writing helpers with support for large numbers, YAML comments, and remote loading:

helpers.js

const {
  parseFile,   // Parse local or remote JSON/YAML files
  stringify,   // Convert to JSON or YAML string
  writeFile,   // Write output to disk
  openapiSort
} = require('openapi-format');

const input = await parseFile('openapi.yaml');
const { data } = await openapiSort(input, { sort: true });

const output = await stringify(data, { format: 'yaml', lineWidth: -1 });
await writeFile('openapi.sorted.yaml', output, { format: 'yaml' });

Note

Both sortSet and sortComponentsSet are optional. When omitted, openapi-format automatically applies built-in defaults.