SHARE THIS ARTICLE

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 description 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 description file into an XML schema (XSD) file?

Transformer allows you to transform between API description files and XSD is not a valid API description file. However, you can choose to convert your API description 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 description file into a JSON schema file?

Transformer allows you to transform between API description files and JSON schema is not a valid API description file. However, you can choose to convert your API description 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 description 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 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 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 description 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 Swagger API description 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.

Troubleshooting

I’m getting the error “We could not identify the API description format from the given file….”. What am I doing wrong?

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

  • 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 description 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 description file, define an API entity on your Dashboard. You will need to provide details like API name, API description, 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 description 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 description 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 description file, define an API entity on your Dashboard. You will need to provide details like API name, API description, 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 description 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 description 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 description 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 tried converting an Insomnia Export file which is currently not supported. You can try converting using a Postman Collection file which is similar to Insomnia or export HAR from your Insomnia app and try converting using that.

  • You are trying to use the URL obtained from exporting an API from your Dashboard for your conversions e.g. URLs starting with https://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.

  • Your file was not in any 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 description file as well as any externally referenced files. Ensure that the relative paths provided in your API description 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.

Getting errors like “Endpoint ABC has a parameter named DEF, which is of an undefined type XYZ.” or “Model ABC has a field named DEF, which is of an undefined type XYZ.”

  • It seems like you tried using a type for your parameter/model fields which was not a supported primitive type of that particular API description format. In such a case, you need to explicitly define that particular type in the relevant section of the API description 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.0.0 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 description 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 description 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 description 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, 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 “Unable to load the file from the remote URL….”. 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 description 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 description 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. information of global tags is lost when converting from Swagger 2.0 to OpenAPI 3.0. 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 accomodate 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 XYZ has no fields. This is not allowed.” for my API Blueprint file? The enum values are declared but the tool is still complaining.

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.


Have questions? Submit a request.