Document Transformation

The library can transform documents between specification versions. This is useful for upgrading older API definitions to newer versions of the specification.

Basic Usage

Call Library.transformDocument() with the source document and the target ModelType.

JavaTypeScript

import io.apitomy.datamodels.Library;
import io.apitomy.datamodels.models.Document;
import io.apitomy.datamodels.models.ModelType;

// Read an OpenAPI 2.0 (Swagger) document
Document swagger = Library.readDocumentFromJSONString(swaggerJson);

// Transform to OpenAPI 3.0
Document openApi30 = Library.transformDocument(swagger, ModelType.OPENAPI30);

// Write out the transformed document
String output = Library.writeDocumentToJSONString(openApi30);

import { Library, Document, ModelType } from '@apitomy/data-models';

// Read an OpenAPI 2.0 (Swagger) document
const swagger: Document = Library.readDocument(swaggerJson);

// Transform to OpenAPI 3.0
const openApi30: Document = Library.transformDocument(swagger, ModelType.OPENAPI30);

// Write out the transformed document
const output = JSON.stringify(Library.writeNode(openApi30), null, 2);

Note

transformDocument() returns a new document. The original document is not modified.

---

Supported Transformations

OpenAPI Upgrades

From	To	Description
OpenAPI 2.0	OpenAPI 3.0	Converts definitions to components/schemas, basePath + host to servers, path-level parameters to operation-level, etc.
OpenAPI 2.0	OpenAPI 3.1	Same as above, plus OpenAPI 3.1-specific changes
OpenAPI 2.0	OpenAPI 3.2	Same as above, plus OpenAPI 3.2-specific changes
OpenAPI 3.0	OpenAPI 3.1	Adjusts schema handling for JSON Schema 2020-12 alignment
OpenAPI 3.0	OpenAPI 3.2	Same as above, plus OpenAPI 3.2-specific changes
OpenAPI 3.1	OpenAPI 3.2	Minimal changes for 3.2 compatibility

AsyncAPI Upgrades

From	To	Description
AsyncAPI 2.x	AsyncAPI 2.y (y > x)	Incremental upgrades within the 2.x series

---

Multi-Step Upgrades

You can chain transformations to upgrade through multiple versions. However, a single call to transformDocument() with the final target version is equivalent — the library handles intermediate conversions internally.

JavaTypeScript

// Direct upgrade from 2.0 to 3.2 in one step
Document openApi32 = Library.transformDocument(swagger, ModelType.OPENAPI32);

// Direct upgrade from 2.0 to 3.2 in one step
const openApi32 = Library.transformDocument(swagger, ModelType.OPENAPI32);

---

Example: Upgrading a Swagger 2.0 Document

JavaTypeScript

String swaggerJson = """
    {
      "swagger": "2.0",
      "info": { "title": "Pet Store", "version": "1.0" },
      "host": "api.example.com",
      "basePath": "/v1",
      "schemes": ["https"],
      "paths": {
        "/pets": {
          "get": {
            "operationId": "listPets",
            "produces": ["application/json"],
            "responses": {
              "200": { "description": "A list of pets" }
            }
          }
        }
      }
    }
    """;

Document swagger = Library.readDocumentFromJSONString(swaggerJson);
Document openApi30 = Library.transformDocument(swagger, ModelType.OPENAPI30);

// The result now has:
// - "openapi": "3.0.3" instead of "swagger": "2.0"
// - "servers" array instead of "host" + "basePath" + "schemes"
// - Response content uses "content" with media types
String result = Library.writeDocumentToJSONString(openApi30);

const swaggerJson = {
    swagger: '2.0',
    info: { title: 'Pet Store', version: '1.0' },
    host: 'api.example.com',
    basePath: '/v1',
    schemes: ['https'],
    paths: {
        '/pets': {
            get: {
                operationId: 'listPets',
                produces: ['application/json'],
                responses: {
                    '200': { description: 'A list of pets' }
                }
            }
        }
    }
};

const swagger = Library.readDocument(swaggerJson);
const openApi30 = Library.transformDocument(swagger, ModelType.OPENAPI30);

// The result now has:
// - "openapi": "3.0.3" instead of "swagger": "2.0"
// - "servers" array instead of "host" + "basePath" + "schemes"
// - Response content uses "content" with media types
const result = JSON.stringify(Library.writeNode(openApi30), null, 2);