openapi-alchemist/README.md

Transform OpenAPI 3 to Swagger 2 with alchemical precision

# OpenAPI Alchemist 🧪

[![CI](https://github.com/Kill-B/api-spec-converter/actions/workflows/ci.yml/badge.svg)](https://github.com/Kill-B/api-spec-converter/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/openapi-alchemist.svg)](https://www.npmjs.com/package/openapi-alchemist)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> ⚠️ **Disclaimer**: This is a fork of [LucyBot-Inc/api-spec-converter](https://github.com/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](https://github.com/LucyBot-Inc/api-spec-converter).

**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

```bash
npm install openapi-alchemist
```

## Usage

### OpenAPI 3 to Swagger 2 Conversion

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

### OpenAPI 3 JSON to YAML Conversion

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

### Using with Objects

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

## 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

```bash
npm run build
```

### Testing

```bash
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](.github/PUBLISHING.md) for detailed publishing instructions.

## License

MIT