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.
Import is Now Much Faster!
Improvement
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.
Improved Warning/Error Messages for Invalid Component Types
Improvement
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 $refs
Improvement
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.
Path Item Level Parameters No Longer Ignored
New
Path item object [v2, v3] level parameter definitions were ignored previously. They are now loaded with complete information including parameter type and description.
- Parameters with location set to
pathwere previously being loaded with type assumed asstringby default anddescriptionwas ignored. They will now be loaded with concrete information provided in the path level parameter definitions.
Impact Level: HIGH
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.
Extra Models Eliminated for Globally Defined Response Schemas
Improvement
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 Level: HIGH
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 title.
Changes to Globally Defined Schemas Import
New
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 Level: HIGH
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.
Changes to Imported Model Names for Inline Schemas
Improvement
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 Status3.
Impact Level: HIGH
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.
Duplicate Paths Are No Longer Allowed
New
If the 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 Level: HIGH
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 allOf Schemas
Bug Fix
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 Level: HIGH
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.
Changes to oneOf Schemas Import
New
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 Object/Dynamic after importing into APIMatic.
Impact Level: HIGH
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.
Invalid $ref Schema Paths Will Not Be Dereferenced
New
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 DefinitionName:
"$ref": "DefinitionName"
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:
"$ref": "#/definitions/DefinitionName"
and for v3.0 it will look like:
"$ref": "#/components/schemas/DefinitionName"
Impact Level: HIGH
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
Improvement
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 Level: HIGH
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
Improvement
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 Level: HIGH
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.
Fixed: Valid $refs That Remained Unresolved Even After Import
Bug Fix
In some rare cases, a valid reference could not be dereferenced properly resulting in fields/parameters/responses to acquire the type Object/Dynamic after importing into APIMatic. This is now fixed.
Impact Level: HIGH
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.
Changes to Null Value Handling in Enums
Improvement
Any unquoted variations of null e.g. null, Null, 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, Null, etc. will now be considered actual values of the enumeration definition.
Impact Level: HIGH
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, Null, etc. from the enum definition if you do not want them to be treated as enum values.
Boolean additionalProperties Now Allowed in OpenAPI v2.0 Import
New
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 Level: MEDIUM
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.
Misplaced $refs Will Be Ignored
New
A $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 Level: MEDIUM
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
Bug Fix
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 Level: MEDIUM
Impact Details: Affected models will now appear with correct names that may impact SDKs, Docs/Portal and API Transformer output where applicable.
Changes to Array Error Response Schemas Import
New
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 Level: MEDIUM
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.
Missing Schema Property Descriptions Will Be Loaded
New
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 Level: LOW
Impact Details: The property level description will now appear in Docs/Portal and API Transformer output where applicable.
Fixed: Decimal Values Getting Changed During Import
Bug Fix
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 Level: LOW
Impact Details: Such example values may change in Docs/Portal and API Transformer output where applicable.
Fixed: Valid Map Type Examples Getting Ignored
Bug Fix
Some valid examples for cases where map type parameter/schemas were involved were getting missed out during import which is now fixed.
Impact Level: LOW
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
New
A $ref used within vendor extensions (those starting with x-) will not be dereferenced anymore.
Impact Level: LOW
Impact Details: Value of the relevant component will no longer show as the dereferenced value in Transformer output where applicable.
User Vendor Extensions Will Not Be Affected by Importer's Metadata
Improvement
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 Level: LOW
Impact Details: Extension values may change accordingly in API Transformer output if applicable.