Skip to main content

Configuring Transformer

You can import/convert your API definition file along with a Metadata file that will allow you to configure various settings for your API when it is imported, and even customize how additional settings can be catered once the file is transformed and exported. You can also configure API Merging for multiple API definition files by specifying the configuration settings.

Import Settings#

These settings allow you to configure the import of your API definition through various options e.g. settings that let you override names of components, etc.

Import Settings Object#

The available properties and their respective types are as follows:

SettingTypePurpose
PreferJsonSchemaNameOverTitleBooleanBy default, this is set to false and if a title is specified in a JSON Schema definition we consider this as the model name. However, when true, we give precedence to the definition name instead of the one specified using property title.
AppendParentNameForClashesBooleanBy default, this is set to false and when loading models/complex types, if there is a clash in names we append a number with the name of the clashing type. When true, the name of the parent component is appended with the name instead. This is currently supported only for import from Swagger v.2.0.
IgnoreRamlTypeDeclarationDisplayNameBooleanBy default, this is set to false. When true, the displayName property for any RAML v.1.0 Type Declaration Object will be ignored and the key name specified at the time of declaring this object will be preferred instead.
PreferSwaggerOperationSummaryOverIdBooleanBy default, this is set to false. When true, we will give more precedence to Swagger Operation Object's summary instead of operationId during endpoint name extraction
AutoGenerateTestCasesBooleanFor several formats like OpenAPI (v3.x), API Blueprint, RAML, Postman and HAR, we support auto-generating test cases from request/response examples (if any are present). By default, this will be enabled but can be disabled by setting this flag to false.
AllowModelTypesWithNoFieldsBooleanBy default, this is set to false. When true, model definitions containing no properties/fields will also be imported.
ImportMultipleResponsesBooleanBy default, this is set to true. When false, any data related to multiple responses including additional types created for these responses will be removed
LoadOneOfAsOptionalFieldsBooleanBy default, this is set to false. When set to true, oneOf schemas will be combined and imported as a single model with all fields considered as optional.
ImportArrayOfMapsAndMapOfArraysBooleanBy default, this is set to false and schemas containing arrays of maps or maps of arrays will be treated as dynamic types during import. When set to true, however, such schema definitions will be imported and the type set accordingly.
ImportTypeCombinatorsBooleanBy default, this is set to true and type combining constructs like union types, anyOf, oneOf and not will be imported. Any extra types associated with these constructs will also be loaded.
UseRamlUnionTypeAsOneOfBooleanBy default, this is set to true and RAML v1.0 union types are loaded as the equivalent of oneOf type construct. If false, the union types are loaded as an equivalent of the anyOf type construct.
ImportWsdlWithJsonMediaTypesBooleanBy default, this is set to false. When set to true, all application/xml request/response media types will be treated as application/json during WSDL import. XML metadata (including details about XML node name, namespace, prefix etc.) will also not be imported.
ImportFromOpenApiDiscriminatorMappingBooleanBy default, this is set to true. When set to false, information from the mapping property in the OpenAPI v3 Discriminator object is not imported.

Example#

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

Export Settings#

These settings let you configure export to various formats e.g. enabling/disabling extensions when exporting to Swagger.

Export Settings Object#

The available properties and their respective types are as follows:

SettingTypePurpose
ExportExtensionsBooleanIf true, any extensions, if supported in the selected export format, will be exported to the output file.
GenerateModelSamplesBooleanBy default, when exporting to Postman (v1.0,2.0), parameter/request/response samples will be auto-generated (where needed) except when importing from WSDL or WADL. Sample generation can be enabled/disabled using this flag.
UseDateTimeOnlyInRamlBooleanIf true, then all date-time fields are exported with type datetime-only instead of datetime in RAML v1.0.
SetPostmanParamValuesAsVariablesBooleanIf true, auto-generated sample values for Postman params (query/path) will be stored inside collection variables instead of being directly embedded in the param definitions. The name of the variable will be the param's name. The values stored in the variables can then be adjusted through the Variables section in Postman's Collection editor.
AddRefSiblingDataInAllOfSchemaBooleanAny sibling data added alongside a $ref is ignored. If any data needs to be added, OpenAPI recommends using allOf to wrap both $ref and that additional data. By default, we ignore sibling data when exporting OpenAPI schemas. However, when set to true, $ref and the data will be added to allOf.
EncodeUrlParamsInPostmanBooleanEnable/disable request URL encoding when exporting to Postman. This is set to true by default.
UseXsdBase64BinaryTypeBooleanBy default, the File or Binary types are exported as xs:hexBinary in XML schemas. If true, the types will be exported as xs:base64Binary instead.
ExportXmlMetaDataBooleanBy default, XML metadata (e.g. XML node name, namespace, prefix, etc.) is set for XML entities when exporting to OpenAPI v3.x, v2.0 or RAML v1.0. If false the XML metadata will not be exported.
ExportDiscriminatorMappingValuesBooleanBy default this is set to true. When set to false, information about discriminator values are not exported to mapping information of the Discriminator object in OpenAPI v3.

Example#

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

API Merging Settings#

You can import multiple API specifications and merge them together to create a unified API Portal and SDK for each language. By default, APIMatic merges APIs using the Take Left merge strategy. When two API definition files are being merged, APIMatic will try to keep elements such as endpoints and schemas from both the APIs. If there is a conflict, the value from the first API will take precedence.

important

For API merging, place the APIMATIC-META.json metadata file (containing the configuration settings) at the root of a directory, and put each API definition (whether it is a single file or composed of multiple files) into individual sub-directories. This directory, with the metadata and API definition sub-directories, is to be provided as a .zip file during import.

SettingTypePurposeDefault Value
MergeApisBooleanEnables merging of APIs.false
MergeSettingsMerge Settings ObjectSettings to configure the merge process. See Merge Settings object for more detail.-
MergeOrderOfDirectories[String]Relative paths to directories that need to be merged. The order of the API definition files in this list matters, as the MergeSettings configuration will be applied based on this order.-
MergedApiNameStringName of the final merged API.-

Example#

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

Merge Settings Object#

The Merge Settings object allows setting the configuration while merging two APIs.

SettingTypePurposeDefault Value
ConflictStrategyEnum[String]Conflict strategy to use when a conflict arises during merge. Possible values are:
  • KeepLeft
  • KeepRight
  • KeepBoth
  • Merge
  • KeepLeft
    DeepCompareFieldTypesBooleanWhether to compare field level referenced custom types by names only or by actually retrieving and comparing their model type definitions.false
    AppendParentNameInNamingConflictBooleanAppend parent name to entity when there is a conflict between names instead of appending a number at the end.false
    SkipCodeGenValidationBooleanConfigures validation of individual APIs and the merged API.false
    NumberStartIndexForNameConflictNumberWhen resolving conflicts in names of components (e.g. endpoints), a number is appended at the end of the conflicting name to make it unique. This setting controls the starting value of this number.1

    Authentication Settings#

    The details on the authentication options available in APIMatic are described here API Authentication. To enable these options via the metafile, you need to specify the authentication object that has the following properties:

    Authentication Object#

    Name: Authentication

    PropertyTypeDetails
    TypeStringMUST be a value from one of [None,Basic, OAuth_v2_BearerToken, CustomQuery,CustomHeader, OAuth_v1_TokenSecret, CustomAuth, JWT, OAuth_v1_Cert_PKCS12_RSA, OAuth_v1a_OneLeggedFlow]
    Parameters[Parameter Object]Array of type Parameter Object

    Example#

    {  "Authentication": {    "Type": "Basic",        "Parameters": [      {        "Name": "username",        "Description": "your username"      },      {        "Name": "key",        "Description": "your api key"      }    ]  }}

    Parameter Object#

    PropertyTypeDetails
    NameStringName of the authentication parameter
    DescriptionStringDetails of the authentication parameter
    DefaultValueStringAny default value for the authentication parameter

    Example#

      {    "Name": "apikey",    "Description": "An API key is required for authentication"  }