Skip to main content

Transformer FAQs and Troubleshooting

FAQs

What do you do with my data?

Your data belongs entirely to you. We do not sell or otherwise do anything with your data to put your privacy at risk.

I want to convert my API definition file to a more readable format. Which format is more suitable?

API Blueprint is a format that uses Markdown which is considered a readable format and is supported widely by GitHub and other documentation renderers.

Can I convert my API definition file into an XML schema (XSD) file?

Transformer allows you to transform between API definition files and XSD is not a valid API definition file. However, you can choose to convert your API definition file to WADL/WSDL which will contain XSD embedded inside it. You can extract XSD from it to accomplish your goal.

Can I convert my API definition file into a JSON schema file?

Transformer allows you to transform between API definition files and JSON schema is not a valid API definition file. However, you can choose to convert your API definition file to OpenAPI formats that contains model definitions using a subset of JSON schema which you can extract and utilize for your purposes.

My Postman Collection file uses environment variables. Is there any support for Postman environment files?

Yes, simply upload a ZIP file that contains your Postman collection file as well as any relevant Postman environment files to get a better output for Postman Collections containing environment variables.

I converted my API definition to WSDL in which XSD is embedded. Is there a way to get a multi-file output where XSD is separated from the actual WSDL files?

Currently we only support a single file output. However, we are looking into supporting this in the future.

My API is described using a OpenAPI/Swagger file. Now I want to make test calls to the API and view responses. Which format is best suited for this?

You can convert your OpenAPI/Swagger file to a Postman Collection file which you can import directly into your Postman App. All your requests will already be populated. You can then simply make your API calls, change the inputs to vary the results and view all the responses in a friendly GUI.

I want to be able to test my RESTful API using SoapUI. Which format should I be using?

For a RESTful API, SoapUI has support for WADL as well as Swagger. You can choose to convert to any of these.

We support conversion from WSDL that is designed to support SOAP based APIs. You have the option to bring in your WSDL API definition and convert it to any of the RESTful formats like Swagger, RAML, WADL. It all depends on what you intend to do with it.

My OpenAPI/Swagger definition file contains extensive documentation for each of the components involved. Conversion to which format has minimal loss of documentation?

The conversion process goes through our internal format during which some documentation may be lost. We are working on improving our support for that. However, much of your documentation should be preserved if you convert to API Blueprint (which is a clean documentation format), RAML, Postman depending on your needs.

I have two OpenAPI definition files in my ZIP folder. When I import the ZIP file, I only see endpoints from the first OpenAPI file while the second OpenAPI file seems to have gotten ignored. What can I do to import both my OpenAPI documents?

A typical transformation only supports transforming a single API definition file at a time. In case of a ZIP file, the first main API definition file located in the ZIP folder is picked up and transformed. If you wish to transform multiple API definition files you can either transform them separately or enable merging in the ZIP folder which will first merge the API definitions together and then transform the merged API definition into the format of your choice.

Troubleshooting

I'm getting the error "We could not identify the API definition format from the given file....". What am I doing wrong?

You may be seeing this error due to any of these common scenarios:

  • Your file was not in any of the supported formats listed at our API Transformer page.

  • You are trying to upload a Blueprint Markdown file but your file does not contain the required format and host information which helps our system distinguish your file from any normal Markdown file. Simply include these two lines at the start of your file and try converting again:

FORMAT: 1A
HOST: http://hostname.com

You can see Blueprint Metadata Section for more details.

  • You are trying to upload a JSON response data file or a JSON schema file or an XML data file which are not valid API definition files. Please ensure your file is in one of the supported formats listed at our API Transformer page. If however, you do not possess an API definition file, define an API entity on your Dashboard. You will need to provide details like API name, API definition, etc. for which you can learn more about in our documentation. Once the API entity is created, go to the Types section and import your JSON/XML file to load the models information. Then export this API entity to get an API definition file which you can then use for your conversions.

  • You are trying to upload an XML schema file (XSD) which is not a valid API definition file. Please ensure your file is in one of the supported formats listed at our API Transformer page e.g. you can try embedding your XSD file into a WADL/WSDL file or upload a ZIP file that contains the WADL/WSDL file as well as any referenced XSD files. If however, you do not possess an API definition file, define an API entity on your Dashboard. You will need to provide details like API name, API definition, etc for which you can learn more about in our documentation. Once the API entity is created, go to the Types section and import your XSD file to load the models information. Then export this API entity to get an API definition file which you can then use for your conversions.

  • You tried uploading a WSDL/WADL file but faced this error. This could be due to invalid XML content. Please ensure that the content of your file validates against any XML validators and then try converting again. Also ensure that the root namespace of the file is valid. For WSDL, it should be http://schemas.xmlsoap.org/wsdl/ and for WADL it should be http://wadl.dev.java.net/2009/02.

note

Support for WADL 2006 format is limited. It is recommended to use the WADL 2009 format instead.

  • You tried uploading a Swagger/OpenAPI file without listing down the required swagger version. For 1.x Swagger files, you need to use the swaggerVersion property, for version 2.0 use the swagger property and for 3.x.x use openapi. Visit the respective specifications of these formats for more details.

  • You tried uploading a RAML fragment file e.g. a RAML library file. A RAML fragment file is not a valid API definition file. A RAML file must be a valid root document in accordance with RAML 0.8 root section or RAML 1.0 root section depending on the version you are using.

  • You tried uploading a valid RAML main file without specifying the RAML version. A RAML file must contain the required comment line indicating the version e.g. for RAML 0.8 the comment line should be #%RAML 0.8 whereas for RAML 1.0 it should be #%RAML 1.0.

  • You tried uploading an API definition file that uses JSON format (e.g. Swagger, Postman, Google Discovery, etc.) but faced this error. Please ensure that the content of the file contains valid JSON using any of the JSON validators available online and then try converting again.

  • You are trying to use the URL obtained from exporting an API from your Dashboard for your conversions e.g. URLs starting with https://www.apimatic.io/apientity/export/…… are obtained that way. You cannot use this URL as it is not a publicly accessible link. Please download the file and then try converting by uploading it to Transformer.

  • The provided URL requires some kind of authentication and is not a publicly accessible link. Please ensure this is not the case and then try converting again.

  • You tried uploading a RAR/7Zip file which are not supported formats. Try converting again by using a ZIP file that contains a file in one of the supported formats listed at our API Transformer page.

I'm getting the error "Unable to resolve reference ..." / "Unable to load RAML Reference….". What should I do ?

The file you uploaded contains references using $ref or !include that could not be resolved. The common causes for this are:

  • The references involved external files that were not provided. In such a case, please upload a ZIP file that contains the main API definition file as well as any externally referenced files. Ensure that the relative paths provided in your API definition file are accurate with respect to the file structure in the ZIP file.
  • The reference contains a URL that is not publicly accessible. Please provide a valid URL that works.
  • The reference is internal (within the same file) but could not be resolved as the entity was not found e.g. if you get error for a reference like "$ref": "#/definitions/DefinitionName" it means that a model definition with the name DefinitionName was not defined under the root definitions property in your file. Provide this missing definition to avoid such errors.

I am getting errors like "Reference to an undefined type found.". What should I do?

You can find documentation for this error here. Common causes of the error are:

  • It seems like you tried using a type for your parameter/model fields which was not a supported primitive type of that particular API definition format. In such a case, you need to explicitly define that particular type in the relevant section of the API definition file. For Swagger 1.x, such types must be defined under models root property, for Swagger 2.0 use definitions root property, for OpenAPI 3.x use schemas root property in the Components section, for RAML 1.0 use types root property while for RAML 0.8, Google Discovery, IO Docs Mashery use schemas root property.

  • API Blueprint does not complain if you use an undeclared type for a parameter or a request/response model. However, our tool requires you to declare these types under the Data Structures section if they are not primitive types supported by API Blueprint itself. A common mistake is using bool instead of boolean.

  • $ref in Swagger 1.x cannot refer to a primitive type. It must point to a Model's id so "$ref": "string" is invalid since string is a primitive type. Use type instead.

  • Be sure to take care of the case of the name. A type may be declared with a different case compared to how it is being referenced. Ensure they are both same and then try again e.g. a type declared as definitionName cannot be referenced as DefinitionName.

I'm getting the error "We do not support importing from an API documentation/reference. Please ensure your file is a raw API definition file and then try importing again". What should I do?

It looks like you tried converting by uploading an HTML file or provided a URL that referred to a web page which was possibly some form of API documentation. This is not supported as the URL/local file must point to a raw API definition file in the formats listed at our API Transformer page and not its documentation/reference. Note that we do have limited support for extracting API definition file from some of the API documentation pages e.g. if you have a URL to a public Apiary documentation of an API like https://apimatic.docs.apiary.io/ we will be able to convert using this. Additionally, some URLs from Swagger UI hosted documentation, MuleSoft Anypoint documentation and Postman docs may also be supported in some cases.

Why am I getting errors/warnings for invalid YAML due to 'Mapping values are not allowed in this context.'?

Swagger 2.0(YAML), OpenAPI(YAML) and RAML requires your files to contain valid YAML content. This error will occur if the YAML content in your file is not valid. You can use tools like YAML Lint to validate your YAML files before transforming them. A few tips to avoid this error are:

  • Every nested item must be indented with two spaces inside the parent one e.g. a property property2 nested inside property1 must be declared as follows:
    property1:
property2:
  • There must be a space between every property name and property value so e.g.
    # This is invalid
property1:propertyValue

# This is valid
property1: propertyValue

In some cases, YAML does not complain if there is no space between property name and value e.g. in case of flow mappings. However, our tool requires you to use space in all cases (even flow mappings).

    # This is invalid
type: { collectionsTypes.mutableResource:{}}

# This is valid
type: { collectionsTypes.mutableResource: {}}

I'm getting the error "Error fetching API definition file from the URL provided....". What should I do?

Please ensure that the URL you provided is publicly accessible, does not require any kind of authentication and points to a raw API definition file in one of the supported formats listed at our API Transformer page e.g. URLs like localhost:XXXX will not work as they are only accessible on your system.

Getting the error for my RAML file "Unable to load external libraries. Please either upload a ZIP File containing all relevant files, or upload by URL." What does this mean?

Your main RAML file (or any fragment file) uses external libraries using the root uses property and these could not be loaded. The common causes for this is:

  • The library file does not exist at the path provided. If you provided your files using a URL then it may be that the relative URL of the library file does not exist or is not accessible. Else you uploaded a single file or a ZIP file with missing files. Ensure that you upload a ZIP file in this case which contains all relevant files.

  • A RAML generally needs the !include tag for referencing external files. However, for referencing external libraries the !include tag must NOT be used.

I converted by API definition to Postman and I seem to have lost any information on types and models. What should I do?

Postman does not store information for your types. If you need to preserve such information, you can try converting to formats like Swagger, RAML,etc. that support data types(primitive and complex).

I see that there is loss of some information when converting my API file from one format to another e.g. some of my descriptions are lost when converting from RAML 1.0 to OpenAPI 3.x. Why is this so?

In the conversion process, there is generally some loss of information which could be due to the following reasons:

  • The particular feature may not be supported by the format you are trying to export to. Please check with the format's official specification to confirm it is indeed supported.
  • We map your file to our internal format during the conversion which is more geared towards our Code Generation engine. However, we are ever working on making it more generic and better suited for conversions. We try to accommodate as much information as possible to minimize this loss so if you feel that something is important but is getting missed out, you are welcome to reach out to us and let us know. We will try to add that as well.

My API is described using WADL and contains multiple GET methods for the same route /xyz. When I convert this to Swagger, I can only see one of the methods in the output. The rest are lost. Is this a bug?

No, it is not a bug. Swagger and RAML supports only one GET method, one POST method, etc. per resource. In the future we are looking into giving you the option to choose the method you want in the converted output out of all the methods in your original file.

Why am I getting this error? "We could not load your API declaration files. Please provide base path information at the root of your file using the 'basePath' property so we can load your API declaration files. Alternatively, import/convert again by providing your file via a URL where the API declaration files are relatively located to the given URL."

Unlike other Swagger formats, Swagger 1.x versions require your files to be structured into two different kind of files: A Resource Listing file and API declaration files. To avoid running into any issues you can do the following:

  • Provide a ZIP file that contains the resource listing file (in the root directory) and the API declaration files in a separate directory relative to this resource listing file. Do ensure that the paths to the API declaration files in the resource listing file are valid with respect to the file structure in the ZIP file.

  • At the time of transforming, provide a URL that points to the resource listing file. The API declaration files must exist relative to this URL. We will automatically try to load them from the paths listed in the resource listing file.

  • Upload a resource listing file that contains the basePath property in the root object that provides the base URL which can be used to load the API declaration files from the relative paths listed in the same resource listing file.

  • Convert by providing a single API declaration file (either by uploading it from your system or via URL).

For more details on the file structure, please visit the specification here.

Why am I getting the error "Enumeration model has no fields which is not allowed." for my API Blueprint file? The enum values are declared but the tool is still complaining.

You can find documentation for this error here. Common causes of the error are:

It looks like enums are used while defining URI parameters and that too without using the Members section. So for example the parameter definition may look like this:

+ Parameters

+ id: 1 (enum[number]) - An unique identifier of the message.
+ 1
+ 2
+ 3

The above will appear in Apiary editor as a list of values:

Without Members

However, the editor does not consider these values as enum values just yet. You need to define them under a Members section using the Members keyword for these to be treated as enum values. So for the above example, the markdown will now look like this:

+ Parameters

+ id: 1 (enum[number]) - An unique identifier of the message.
+ Members
+ 1
+ 2
+ 3

This should take away the error you were facing while converting your files. Also if you now see the Apiary editor, the list of values will be shown as a list of possible values:

With Members

You can visit URI Parameters Section for more details on how to declare URI parameters in API Blueprint.

I see some extra models in the converted file which were not present in the original file. Why is that?

Other than the models defined explicitly in the API definition by the user, we may create extra models in certain scenarios which are:

  1. Any enum values declared inline for parameters/responses/model fields are loaded as models and may appear that way in case of certain conversions.
  2. In certain cases where type information is not provided but an example is included we infer models from the example e.g. we automatically generate a model from the Request Body example given for any API Blueprint action request if its schema is not defined/indicated explicitly.
  3. If error responses use any models we load them separately as exception models internally. You may see these models in the output if you convert to formats like APIMatic.
  4. Any inline model declaration like the ones supported in RAML and OpenAPI are also loaded as explicit models.

In all of the above cases, the names of the models are generally derived from the component name (e.g. parameter name). Due to this, there is a chance that this derived model name may clash with other derived model names or with names of user defined models. We try to handle such clashes by appending a number at the end of the derived model so names like Model1, Model2, Model3, etc. may appear in the output. If you are using inline models, we recommend that you either move such definitions to the global level and assign them a unique name or in case of OpenAPI use the property title to assign unique names to the inline models. If inline models are not the root cause or it is not possible to modify the original specification document, we recommend that you use our metadata file import configuration setting AppendParentNameForClashes to assign parent name to clashing model names instead of numbers as this can improve the output quality to some extent. You can learn more about our API Metadata file here.

I used your Transformer to convert my WSDL file to OpenAPI format. However, when I try using the OpenAPI file to make calls to my API, the calls fail. Why is that happening?

Our WSDL to OpenAPI conversion is designed to facilitate migration of SOAP APIs to REST APIs. The conversion involves translating the SOAP API information into a REST API compatible information. In other words the converted output can not be used to work for your existing SOAP API. You will need structural changes on your API's end to make your API work as a REST API before you can make any API calls using the converted output.

I converted my OpenAPI file to a Postman Collection and am seeing some dummy sample values for my responses that did not exist in my OpenAPI file. Why is this happening?

You are seeing dummy sample values because we auto-generate sample values when exporting to Postman Collections and Insomnia if your original specification document does not contain any examples of its own. To disable this feature, you can upload an APIMatic Metadata file and set the GenerateModelSamples export setting to false.