Our OpenAPI importers (both v2.0 and v3.0) have undergone a complete overhaul that includes some major performance improvements, bug fixes and other refinements.
A detailed breakdown of the changes is given below. Please review these changes carefully as the way your file gets imported can impact your SDK generation, Docs/Portal generation as well as API Transformer output.
These changes will only affect you if you choose to re-import or re-transform your OpenAPI files.
The release includes major performance improvements especially for files containing a lot of references (above 500) using
$ref. You should now be able to import all your files that are less than 15MB in size in less than 1 minute.
If a component was found to have an unexpected type with respect to the official OpenAPI specification e.g. if an object was expected but an array was found, the error shown during import was unclear and rather complex. It also lacked information about which file the issue was found in and its location within that file. Now, the error messages for type related issues have been made user friendly and will contain complete details including the file in which the issue exists as well as the line number and line position.
Improved Error Messages for Unresolvable
A user could only find out about the first unresolvable
$ref in his file when the import failed due to this. This was especially troublesome if a user's file contained more than 10 such references and, therefore, he needed to fix and import his file more than 10 times to get the import to work. Now, however, users can get information about all unresolvable $refs with a single import along with details about file and line number indicating exactly where such
$refs were found.
- Parameters with location set to
pathwere previously being loaded with type assumed as
stringby default and
descriptionwas ignored. They will now be loaded with concrete information provided in the path level parameter definitions.
Impact Details: Existing parameter types may change as well as new parameters may be loaded in SDKs, Docs/Portal and API Transformer in accordance with the definitions found at path item level as described above.
Workaround: You will need to remove the parameters defined at path item level to get the output as before.
Schemas defined in-line within Response objects (i.e. not globally defined under
definitions in v2.0 or under
components/schemas in v3.0) without containing a
title, were loaded with name of the Operation in which the response was defined or with a name generated from the Operation's relative path. However, now in cases where response objects reference global responses defined under root object's
responses in v2.0 or under
components/responses in v3.0, the response schema model will now be loaded with the name of the global response definition. This will help prevent loading the same response's schema each time with a different name and will thus result in less extra models.
Impact Details: In above case, only one model will be loaded while all extra models will be removed from SDKs, Docs/Portal and API Transformer output where applicable.
Workaround: To get the output as before, you will have to remove global responses and instead define response schemas independently for each operation with the desired
If a globally defined schema (under
components/schemas in v3.0 or under
definitions in v2.0) directly references another globally defined schema in its definition body and the inner referenced schema has no
title property, then both schemas will now be loaded as two separate types after importing into APIMatic.
Impact Details: New types may appear as a result of this in SDKs, Docs/Portal and API Transformer output where applicable.
Workaround: You may use
title in the inner referenced type to give your schema the desired name and to load both types as a single type as before.
Schema definitions that are not globally defined like under
definitions in v2.0 or under
components/schemas in v3.0 are imported in APIMatic with names inferred from property/parameter names in which these schemas are defined. Duplicate names are handled by appending a number at end of the name. It was noticed that some types were assigned higher number values even when lower ones could be assigned. This is now fixed. Due to this, you may notice that for some types names will now have a lower number value attached with them compared to before e.g. a type loaded as
Status5 may now be loaded as
Impact Details: Names of such types may now become changed in SDKs, Docs/Portal and API Transformer output where applicable.
Workaround: Add a desired
title for such schemas to override the names and restore them to their original values.
paths object [v2, v3] contains duplicate path entries, the OpenAPI file will be treated as invalid and no longer imported. Previously, the importer simply ignored duplicate paths and loaded the rest of the information.
Impact Details: If your files contain this issue, you will no longer be able to import them into APIMatic until you remove the duplicate entries.
Fixed: Incorrectly Imported
When importing a schema that uses
allOf, APIMatic first combines the schemas within
allOf into one and creates a new schema out of it which is then imported. However, in some cases it was noticed that the first
allOf schema item was imported as the final schema instead of the new combined schema. This is now fixed and may result in new types.
Impact Details: Correct import of
allOf schemas may result in modification of existing or addition of new models that can impact SDKs, Docs/Portal and API Transformer output where applicable.
oneOf Schemas Import#
APIMatic does not currently support
oneOf schemas. However, in some rare cases,
oneOf schemas got imported as a single model with optional fields. This is now disabled by default and any component referencing such schemas will now be assigned the type
Dynamic after importing into APIMatic.
Impact Details: If your file contains such schemas, some models may now be removed and their references updated accordingly in your SDKs, Docs/Portal and API Transformer output where applicable.
Workaround: You can upload a Metadata file along with your specification at the time of importing, with the
LoadOneOfAsOptionalFields import setting enabled to load all
oneOf schemas as models with optional fields.
$ref Schema Paths Will Not Be Dereferenced#
For specs containing direct references to a global schema (those defined under
definitions in v2.0 or under
components/schemas in v3.0) in the
$ref path will no longer be dereferenced e.g. the following case shows a direct reference made to a global schema named
This is invalid and will no longer be dereferenced and an error will be thrown instead. Only valid
$ref paths will be entertained e.g. in case of v2.0 a valid path would look like:
and for v3.0 it will look like:
Impact Details: If your files contains invalid references like these, you will need to correct them to avoid any issues during import.
Operations Containing Invalid
$refs in Parameters Will Now Be Imported#
In OpenAPI, you can only use
$ref to reference another component of the same type. This means you cannot reference a Parameter object inside a Schema object or vice versa. If, in an Operation object [v2, v3], a Parameter object [v2, v3] tried referencing a Schema object [v2, v3] directly using
$ref, the importer did not import the whole Operation object in which the parameter resided. However, now the operation is loaded and only the Parameter object is not loaded.
Impact Details: If a case like above exists in your spec, a new endpoint will be added upon import which will impact SDKs, Docs/Portal and API Transformer output where applicable. If there are any inline schemas defined in the endpoint they will also be imported. Addition of new models can also impact SDKs, Docs/Portal and API Transformer output where applicable.
Workaround: To get the output as before, you will need to remove the concerned Operation object from your spec.
$ref As a Schema Property Now Allowed#
If an object schema was defined in which a property was named as
$ref, it was ignored as the name conflicted with the reserved key
$ref used for referencing components. However, now such schema properties will no longer be ignored.
Impact Details: Schema properties named
$ref will now be loaded into model properties that can impact SDKs, Docs/Portal and API Transformer output where applicable.
Workaround: You can remove the
$ref property from schema properties definition to get the output as before.
$refs That Remained Unresolved Even After Import#
In some rare cases, a valid reference could not be dereferenced properly resulting in fields/parameters/responses to acquire the type
Dynamic after importing into APIMatic. This is now fixed.
Impact Details: Affected components will now have correct types assigned to them that can result in changes in SDKs, Docs/Portal and API Transformer output where applicable. In case the type involved complex models/schemas, it is possible that new models may appear after import that can also impact SDKs, Docs/Portal and API Transformer output where applicable.
Any unquoted variations of null e.g.
NULL, etc. in
enum definitions were not imported as enumeration values in APIMatic. Now, if a value equal to
null is found, the enumeration list will be considered a
nullable enum property/parameter/schema and this value will be removed from the enumeration list when importing into APIMatic. However, all other variations of this value like
Null, etc. will now be considered actual values of the enumeration definition.
Impact Details: Values of enumeration models may be affected accordingly in SDKs, Docs/Portal and API Transformer output where applicable. Properties/parameters/schemas referencing such enums may be treated nullable in some cases which can also impact API Transformer output where applicable.
Workaround: If you want
null to be treated as an enum value and avoid properties/parameters/schemas from becoming nullable you may need to quote the value like
"null". You will have to remove values like
Null, etc. from the enum definition if you do not want them to be treated as enum values.
additionalProperties Now Allowed in OpenAPI v2.0 Import#
Support for boolean type
additionalProperties in our OpenAPI v2.0 importer has now been added which was previously causing an error during import for some users.
Impact Details: You should now be able to import your files successfully that contained boolean type
additionalProperties in v2.0. This will not, however, impact output of SDKs, Docs/Portal or API Transformer.
$refs Will Be Ignored#
$ref used inside an object where OpenAPI does not allow usage of
$ref will no longer be dereferenced. Please check the OpenAPI official documentation for more details about valid $refs.
Impact Details: Value of the relevant component will no longer show as the dereferenced value in Docs/Portal and API Transformer output where applicable.
Fixed: Incorrect Model Names When Using
PreferSchemaNameOverTitle Import Setting#
Even when using import setting
PreferSchemaNameOverTitle, some model names were neither being loaded from their global schema name nor
title but instead were being inferred from property/parameter names in which these schemas were referenced. This is now fixed.
Impact Details: Affected models will now appear with correct names that may impact SDKs, Docs/Portal and API Transformer output where applicable.
If your error response schemas directly reference an array schema, then the inner schema of this array that describes the array items may now be loaded with the
_Error postfix after importing into APIMatic.
Impact Details: If such a case exists in your file, then error model names may get changed in SDKs, Docs/Portal and API Transformer output where applicable.
Workaround: Define the inner model globally under
definitions in case of v2.0 or under
components/schemas in case of v3.0 and assign it the desired name. It will then be loaded as before.
For schema properties referencing, using
$ref, other schemas that contain a
description property, the
description will now also be loaded as the property's description during import.
Impact Details: The property level
description will now appear in Docs/Portal and API Transformer output where applicable.
Decimal point values used in examples were often affected during import e.g. a value
37.777709 was being loaded as
37.77771. We have fixed the issue and the values will no longer be affected.
Impact Details: Such example values may change in Docs/Portal and API Transformer output where applicable.
Some valid examples for cases where map type parameter/schemas were involved were getting missed out during import which is now fixed.
Impact Details: Previously such ignored examples will now show up in Docs/Portal and API Transformer output where applicable.
$refs Within Vendor Extensions Will Be Ignored#
$ref used within vendor extensions (those starting with
x-) will not be dereferenced anymore.
Impact Details: Value of the relevant component will no longer show as the dereferenced value in Transformer output where applicable.
In some cases, the vendor extensions data specified in the OpenAPI description got modified because of the importer inserting importer-specific metadata like
id, etc. This is fixed and user data will no longer be modified.
Impact Details: Extension values may change accordingly in API Transformer output if applicable.