Transform OpenAPI 3 to Swagger 2 with alchemical precision
npm install openapi-alchemist


> ⚠️ Disclaimer: This is a fork of LucyBot-Inc/api-spec-converter, converted to TypeScript and focused on OpenAPI 3 to Swagger 2 conversion. For the original full-featured converter supporting multiple formats, please visit the original repository.
Transform OpenAPI 3 to Swagger 2 with alchemical precision ✨
A TypeScript-converted minimal and focused API specification transformer that converts OpenAPI 3 to Swagger 2 with surgical accuracy.
This package provides two main functionalities:
1. OpenAPI 3 → Swagger 2 transformation ✨
2. OpenAPI 3 JSON ↔ YAML format conversion (semantic preservation, format-only conversion)
This version has been converted to TypeScript for Node.js v22+ with modern Promise-based APIs and improved type safety.
``bash`
npm install openapi-alchemist
`javascript
const openapiAlchemist = require('openapi-alchemist');
// Transform OpenAPI 3 specification to Swagger 2
openapiAlchemist.convert(
{
syntax: 'yaml',
order: 'openapi',
from: 'openapi_3',
to: 'swagger_2',
source: './path/to/your/openapi3.yaml', // or object
},
function (err, converted) {
if (err) {
console.error('Error converting:', err);
return;
}
// Output as YAML
const yamlString = converted.stringify({syntax: 'yaml'});
console.log(yamlString);
// Output as JSON
const jsonString = converted.stringify({syntax: 'json'});
console.log(jsonString);
}
);
`
`javascript
const openapiAlchemist = require('openapi-alchemist');
// Transform OpenAPI 3 JSON to YAML (format conversion only)
openapiAlchemist.convert(
{
syntax: 'yaml',
order: 'openapi',
from: 'openapi_3',
to: 'openapi_3', // Same format, different syntax
source: './path/to/your/openapi3.json',
},
function (err, converted) {
if (err) {
console.error('Error converting:', err);
return;
}
// Output as YAML
const yamlString = converted.stringify({syntax: 'yaml'});
console.log(yamlString);
}
);
`
`javascript
const openapiAlchemist = require('openapi-alchemist');
const openApiSpec = {
openapi: '3.0.0',
info: {
title: 'My API',
version: '1.0.0'
},
paths: {
'/users': {
get: {
responses: {
'200': {
description: 'Success',
content: {
'application/json': {
schema: {
type: 'object',
properties: {
users: {
type: 'array',
items: {
type: 'string'
}
}
}
}
}
}
}
}
}
}
}
};
openapiAlchemist.convert(
{
from: 'openapi_3',
to: 'swagger_2',
source: openApiSpec, // Direct object
},
function (err, converted) {
if (err) {
console.error('Error:', err);
return;
}
console.log('Converted successfully!');
console.log('Swagger version:', converted.spec.swagger);
}
);
`
Transforms API specifications between supported formats.
#### Parameters
- options (Object):from
- (String): Source format ('openapi_3')to
- (String): Target format ('swagger_2' or 'openapi_3')source
- (String|Object): Source specification (file path or object)syntax
- (String, optional): Output syntax ('json' or 'yaml', default: 'json')order
- (String, optional): Output ordering ('openapi', 'alpha', or 'false', default: 'openapi')
- callback (Function): Callback function with signature (err, result)
#### Return Value
The callback receives a result object with:spec
- : The converted specification objectstringify(options)
- : Method to convert the spec to string format
- Node.js >= 22.0.0 (TypeScript version with modern Promise APIs)
This minimal version does not support:
- RAML specifications
- API Blueprint specifications
- WADL specifications
- Google Discovery documents
- I/O Docs specifications
- Swagger 1.x specifications
- URL-based sources (only file paths and objects)
- Swagger 2 → OpenAPI 3 conversion
This package is built with TypeScript and compiled to CommonJS for Node.js compatibility. The source code is in the src/ directory and compiled output is in dist/.
`bash`
npm run build
`bash`
npm test
1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)git commit -m 'Add some amazing feature'
3. Commit your changes ()git push origin feature/amazing-feature`)
4. Push to the branch (
5. Open a Pull Request
See .github/PUBLISHING.md for detailed publishing instructions.
MIT