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:

Setting	Type	Purpose
PreferJsonSchemaNameOverTitle	Boolean	By 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.
AppendParentNameForClashes	Boolean	By 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.
IgnoreRamlTypeDeclarationDisplayName	Boolean	By 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.
PreferSwaggerOperationSummaryOverId	Boolean	By 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
AutoGenerateTestCases	Boolean	For 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.
AllowModelTypesWithNoFields	Boolean	By default, this is set to false. When true, model definitions containing no properties/fields will also be imported.
ImportMultipleResponses	Boolean	By default, this is set to true. When false, any data related to multiple responses including additional types created for these responses will be removed
LoadOneOfAsOptionalFields	Boolean	By 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.
ImportArrayOfMapsAndMapOfArrays	Boolean	By 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.
ImportTypeCombinators	Boolean	By 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.
UseRamlUnionTypeAsOneOf	Boolean	By 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.
ImportWsdlWithJsonMediaTypes	Boolean	By 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.
ImportFromOpenApiDiscriminatorMapping	Boolean	By default, this is set to true. When set to false, information from the mapping property in the OpenAPI v3 Discriminator object is not imported.
ImportRequestBodyContentTypeHeader	Boolean	By default, this is set to true. When set to false, request's content type information will not be imported as explicit Content-Type header.
ImportMultipleAuthentication	Boolean	By default, this is set to true and all authentication schemes available in the API are loaded as is. When set to false, however, only the first authentication scheme from the API will be imported.
ImportOpenApi3EmptySchema	Boolean	By default, this is set to true and the schema declaration will not be ignored. If set to false an empty schema will be treated as if no schema was declared.
LoadBaseTypesForOneOfAnyOfDiscriminator	Boolean	By default, this is set to true and additional base types will be created for cases where discriminator information is present alongside oneOf or anyOf. When set to false, no additional base types will be created and exporting to formats where discriminator is not supported alongside oneOf/anyOf may see loss of information related to it.
ImportTypeCombinatorsWithOnlyOneType	Boolean	By default, this is set to true and type combinators (e.g. anyOf, oneOf, not) containing only one type definition in their list will be imported as is. When set to false, the type combinators lists will not be populated. Instead, the single type definition will be extracted from the list and considered as the default type of the component.
AppendParentSchemaNameToOneOfAnyOfBaseType	Boolean	By default, this is set to false and base types auto-generated from cases involving oneOf/anyOf discriminators will have default names. When set to true, the name of the parent schema may be appended with the default name, if applicable. This is recommended for cases where multiple oneOf/anyOf schemas are expected to have the same discriminator property name.

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:

Setting	Type	Purpose
ExportExtensions	Boolean	If true, any extensions, if supported in the selected export format, will be exported to the output file.
GenerateModelSamples	Boolean	By 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.
UseDateTimeOnlyInRaml	Boolean	If true, then all date-time fields are exported with type datetime-only instead of datetime in RAML v1.0.
SetPostmanParamValuesAsVariables	Boolean	If 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.
AddRefSiblingDataInAllOfSchema	Boolean	Any 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.
EncodeUrlParamsInPostman	Boolean	Enable/disable request URL encoding when exporting to Postman. This is set to true by default.
UseXsdBase64BinaryType	Boolean	By 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.
ExportXmlMetaData	Boolean	By 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.
ExportDiscriminatorMappingValues	Boolean	By 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.
ExportAnyType	Boolean	By default, this is set to true and type any will be exported where applicable. When set to false, type any will be exported as object/string instead.
ExportGlobalTypeCombinators	Boolean	By default, this is set to true and global type combining constructs e.g. anyOf, oneOf, not or union types will be defined once globally and the referencing schemas will refer them via their unique name/path in applicable formats like OpenAPI v3.0 and RAML. When set to false, the global type combining schemas will be embedded inline in all schemas referencing them.
ExportOptionalParametersAsDisabled	Boolean	By default, this is set to false and optional parameters are enabled in exported Insomnia and Postman Collection files. When set to true, request parameters marked as optional will appear disabled in the aforementioned types of files, upon export.
ExportApiKeyAuthInPostman	Boolean	By default, this is set to true and if a request in Postman needs an API key to be sent as a header/query parameter, it is set as its authentication type. When set to false, the API key is instead added as an explicit request parameter. This is especially recommended for cases where a request needs multiple API keys to be sent as part of its authentication, which is a scenario otherwise not supported in Postman authentication types.
GenerateSampleValueFromRegexPattern	Boolean	By default, this is set to false due to performance overhead. When set to true and a regex pattern is specified, the sample value will be generated based on the specified regex pattern in case of export to Insomnia or Postman Collection.
UseHttpMethodPrefixForAutoGeneratedWsdlNames	Boolean	By default, this is set to true. When set to false, WSDL export will not add endpoint's HTTP method as a prefix to auto-generated names of related components e.g. names of schema types, operation name, etc.

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.

Setting	Type	Purpose	Default Value
MergeApis	Boolean	Enables merging of APIs.	false
MergeSettings	Merge Settings Object	Settings 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.	-
MergedApiName	String	Name 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.

Setting	Type	Purpose	Default Value
ConflictStrategy	Enum[String]	Conflict strategy to use when a conflict arises during merge. Possible values are: KeepLeft KeepRight KeepBoth Merge	KeepLeft
DeepCompareFieldTypes	Boolean	Whether to compare field level referenced custom types by names only or by actually retrieving and comparing their model type definitions.	false
AppendParentNameInNamingConflict	Boolean	Append parent name to entity when there is a conflict between names instead of appending a number at the end.	false
SkipCodeGenValidation	Boolean	Configures validation of individual APIs and the merged API.	false
NumberStartIndexForNameConflict	Number	When 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
MergeMultipleAuthentication	Boolean	Allow more than one authentication schemes present in the individual APIs, or the APIs being combined, to be merged together.	true

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

Property	Type	Details
Type	String	MUST 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

Property	Type	Details
Name	String	Name of the authentication parameter
Description	String	Details of the authentication parameter
DefaultValue	String	Any default value for the authentication parameter

Example

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