Skip to main content

Rolling Out Long Awaited Major Improvements to Transformer

· 4 min read

For the past few months, we have been hard at work improving API Transformer to give our users good quality output for any of their conversions. This changelog highlights all improvements made and new features added which we plan to release in a few weeks from now. To get full advantage of these improvements, some of the users who import from various formats like OpenAPI/Swagger, API Blueprint, etc. may need to regenerate their portal/SDKs.

Details​

The changes involve improvements, bug fixes and feature addition which are a result of a major overhaul of all our format parsers. Some of the notable changes are highlighted in the sections below.

Bug Fixes​

  • Definitions for user-defined models/complex types whose names clashed with reserved primitive types like string, number, etc. were lost during the conversion process for any of the supported formats. We have now added mechanisms to prevent this from happening.

Improvements​

  • The order as well as the names of the user-defined types will now be preserved. Previously, these types were loaded and fetched dynamically, as needed, which did not guarantee the original order of the types. Also, when name conflicts arose during this dynamic loading, there was a possibility of names of the original types getting modified as well. We now try to preserve the user defined order and naming where possible.
note

The types can still be renamed in rare cases where there is a clash of names that are different only in the case used e.g. user and User are considered same by our tool and will be renamed to user and User1 respectively.

  • Order of operations/methods was not preserved for conversions to and from OpenAPI/Swagger (v1.2, 2.0, 3.0) and RAML (v1.0) formats. This will now be preserved.

  • Although, we don't fully support allOf used in JSON schemas and OpenAPI(v3.0) schemas, we have largely improved the support by preserving as much information as possible when combining schemas using this keyword.

  • Inconsistencies in support for arrays and enums when converting to API Blueprint have been removed. This includes improvements for support in URI parameters, request/response attributes and MSON data structures.

  • Loss of descriptive content during the conversion process has been largely reduced. This includes documentation and descriptions provided for the API, endpoint parameters, responses and model fields.

  • Format specific reserved keywords have been taken into consideration when conversion is being made to these formats e.g. RAML (v0.8/v1.0) does not allow types to have names that conflict with the RAML primitive types. A type like string will, therefore, be renamed to string1 to help users avoid issues using the exported RAML file. Similarly, other format specific restrictions have been taken into account as well.

  • As part of our conversion process, we treat models for success and error responses differently. This generally involves creation of different models internally for each, which lead to users seeing extra models in the exported files. This has been fixed.

New Additions​

  • New settings have been introduced to let users configure the conversion process.

    • A setting that allows user to control how our tool handles clashes between same named types/models. The default mechanism will be to append a number to one of these types but the user can opt for a mechanism that appends the parent name instead.
    • A setting to enable/disable our auto testcase generation feature when importing from formats that supports examples e.g. API Blueprint, OpenAPI, RAML, Postman, etc.
    • A setting to enable/disable our auto-sample generation when exporting to Postman.
    • A setting to enable/disable Swagger (v2.0) and API Blueprint extensions in the output files.

    Details on how to use these settings will be available in our Metadata section upon release.

  • Support for error responses and their model definitions was missing for conversion from Swagger v1.2 and WADL and conversion to API Blueprint. It has now been added.