Skip to main content

Configuring Transformer

As explained here, an API specification transformation internally involves both import and export stages behind-the-scenes. Both these stages can be configured individually for which two major ways are described below:

  1. Using APIMatic Metadata Configuration Options.
  2. Using Format-Specific Vendor Extensions.

Using APIMatic Metadata Configuration Options​

You can transform your API definition/specification along with the APIMatic's Metadata file that will allow you to do the following:

Configuring Import​

You can control and customize how your file is imported during the transformation process e.g. you can configure the import process to use the schema keys instead of schema titles during OpenAPI import.

Import Settings​

The import level configuration is performed by using import settings that are provided inside the APIMatic Metadata file Import Settings Object.

Import Settings Object​

The available properties in this object and their respective types are listed here.

Example​

{
    "ImportSettings": {
        "PreferJsonSchemaNameOverTitle": true,
        "AppendParentNameForClashes": true,
        "AllowModelTypesWithNoFields": true
    }
}

Configuring Export​

You can control and customize how your input file is exported during the transformation process e.g. you can enable/disable export of vendor extensions when exporting to OpenAPI.

Export Settings​

The export level configuration is performed by using export settings that are provided inside the APIMatic Metadata file Export Settings Object.

Export Settings Object​

The available properties and their respective types are listed here.

Example​

{
    "ExportSettings": {
        "ExportExtensions": true,
        "GenerateModelSamples": true
    }
}

Merge and Transform​

If you have multiple API definitions that you wish to merge together and produce a single transformed file in a particular format, you can enable merging in the ZIP folder you upload.

note

Merging multiple definitions is different from handling multiple files of a single API definition, which is handled by the Transformer automatically.

To enable and further configure merging, you need to add a Merge Configuration Object in the Metadata file.

API Merging Settings​

The available merging configurations are listed here. These configurations further contain a Merge Settings Object to configure how any two APIs are merged together.

Example​

{
    "MergeConfiguration": {
        "MergeApis": true,
        "MergeOrderOfDirectories": ["SpecDirectory1", "SpecDirectory2"],
        "MergedApiName": "Merged API",
        "MergeSettings": {
            "ConflictStrategy": "KeepLeft",
            "SkipCodeGenValidation": true
        }
    }
}

Merge Settings Object​

The Merge Settings Object allows configuration of the merge process. The settings available are listed here.

When merging multiple API definitions for purpose of transforming the output, we recommend that you turn off strict validation meant specifically for Code Generation use-cases. This can be done by enabling the merge setting SkipCodeGenValidation as shown in the example in the previous section.

Filter Before You Transform​

If you wish to remove certain endpoints (for privacy reasons or any other) and their related data from the API specification document without actually affecting the original document, you can enable filtering using filtering options in the Metadata file. For more details, please see relevant section here.

Override Parts of API Definition Before You Transform​

If you are looking to override certain parts of the API definition before transforming it, you can take a look at some of the overrides available in the Metadata file here.

Using Format-Specific Vendor Extensions​

We also support format-specific vendor extensions (e.g. for OpenAPI/Swagger, RAML and API Blueprint) so you can fine-tune the transformation output from within your API specification file. For details, please refer to our detailed documentation on Extensions specific to your API definition file.