API Transformer Overview
You can convert API definition/specification files into any format of your choice from amongst more than 10 supported formats including OpenAPI (previously known as Swagger), RAML and API Blueprint (complete list available in the later sections). This allows you to fully utilize all tools and functions that come with each format and saves the extra cost of having to rewrite your API definitions all over again.
How Does Transformer Work?
The API specification document you input goes through the following steps internally while you're only performing a one step - transformation:
- The API specification is imported.
- The imported API definition is validated.
- If the API passes validation, the API is converted/exported to desired format.
When an API definition passes through the import phase during transformation it is not added to the Dashboard as is the case when explicitly importing an API.
Configure Transformer
You can fine-tune and customize the transformation process according to your needs. This includes the ability to configure both import and export stages of the transformation and much more. Please visit our related documentation on this topic here.
Supported Formats in API Transformer
Refer to the lists below for detail on which versions and formats are supported for input and output of the Transformer:
Supported Input Formats
The API Transformer supports the following API specification formats as input and converts them into the selected output format:
| API Specification Format | Version | File Format |
|---|---|---|
| OpenAPI/Swagger | 3.1 3.0 2.0 1.x | JSON/YAML JSON/YAML JSON/YAML JSON |
| RAML | 1.0 0.8 | YAML YAML |
| Postman Collection | 2.0 1.0 | JSON JSON |
| Insomnia | 3 | JSON/YAML |
| HAR | 1.2 | JSON |
| API Blueprint | 1A | Markdown |
| WADL - W3C | 2009 | XML |
| WSDL - W3C | 1.1 | XML |
| Google Discovery | - | JSON |
| I/O Docs - Mashery | - | JSON |
| APIMATIC | - | JSON |
Transforming an API Specification With Multiple Files
If your API specification document is split up into multiple files for reusability purposes or any other reasons, we recommend that you create a ZIP file and add all relevant files to it. Then, upload this ZIP file when transforming. Ensure that all referenced files are part of the ZIP file and all relative paths to the files within the ZIP file are valid, to avoid any issues during the transformation e.g. if you are uploading a RAML ZIP file, ensure that all files referenced using !include or $ref are all present in the uploaded ZIP file.
It is recommended that in a ZIP file, the main API specification file is present in the root directory. If that is not the case, Transformer will iterate the ZIP file contents and pick the first file that validates as a main file in one of the supported input formats.
Transforming Multiple API Specifications
If you wish to transform multiple API specifications to generate a single API specification in any format, then you need to enable merging in the root directory, ZIP all files and then transform the ZIP file. It is very important to correctly structure the API specification documents when merging, to get desired results.
When merging multiple API definitions for purpose of transforming the output, we recommend that you turn off strict validation meant specifically for Code Generation use-cases. This can be done by enabling the merge setting SkipCodeGenValidation.
Supported Output Formats
The API Transformer supports conversion of the provided input API specification into the following formats:
| API Specification Format | Version | File Format |
|---|---|---|
| OpenAPI/Swagger | 3.1 3.0 2.0 1.2 | JSON/YAML JSON/YAML JSON/YAML JSON |
| RAML | 1.0 0.8 | YAML YAML |
| Postman Collection | 2.0 1.0 | JSON JSON |
| Insomnia | 3 | JSON/YAML |
| API Blueprint | 1A | Markdown |
| WSDL - W3C | 1.1 | XML |
| WADL - W3C | 2009 | XML |
| GraphQL Schema | - | GraphQL |
| APIMATIC | - | JSON |