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.

Features

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.

Installation

npm install openapi-alchemist

Usage

OpenAPI 3 to Swagger 2 Conversion

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);
  }
);

OpenAPI 3 JSON to YAML Conversion

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);
  }
);

Using with Objects

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);
  }
);

API Reference

convert(options, callback)

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 object
• stringify(options): Method to convert the spec to string format

Supported Node.js Versions

• Node.js >= 22.0.0 (TypeScript version with modern Promise APIs)

What's Not Supported

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

Development

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/.

Building

npm run build

Testing

npm test

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Publishing

See .github/PUBLISHING.md for detailed publishing instructions.

License

MIT