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.

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.0), 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.

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:

Settings TypeTypePurpose
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.0, v2.0 or RAML v1.0. If false the XML metadata will not be exported.

Example#

{
"ExportSettings": {
"ExportExtensions": true,
"GenerateModelSamples": 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

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"
}