- October 26, 2015

We recently added a cool capability to the already-extensive palette of multi-language support and translation in APISpark: the ability to import RAML definitions! Now you can both import and export RAML, just like you already could do with Swagger. Furthermore, it’s also possible to import “multi-file” definitions, by importing RAML and Swagger APIs that span multiple files. Last but not least, these import and export capabilities also mean that you can easily translate existing APIs from RAML to Swagger or Swagger to RAML.

This can be illustrated through a quick walkthrough, in which we will import a sample multi-file RAML API definition in APISpark.

When in the APISpark dashboard, click on the Web API creation button (but you can also create it from the Quick Start Wizard as well, which you can launch via the magic wand icon):


The following dialog box will show up, and you’ll be able to give your API a name:


You can select “descriptor” or “connector”, depending on whether you want to document an API (to do API definition translations, to download client SDKs or server skeletons, or download HTML documentation), or whether you want to manage an existing API (to enhance an API with security, rate limitation, IP filtering, analytics…)

In the tools menu, the button with the little cog icon in the top right hand corner, you’ll be able to click on the “Import definition” option:


A dialog box will ask you what format of API definition you want to import (here I want to import a RAML 0.8 definition), and I want to upload the definition by file from my computer (note that you can also point at an existing online API definition by selecting the ‘URL’ source):


For the purpose of this article, I took the RAML 200 tutorial, I cloned the associated Github repository, and I zipped up the API definition in a zip file. I then clicked the “Choose a file” button to upload this multi-file API definition in RAML. When this happens, you’ll see the dialog box updated with the ability to select the main entry point of your API definition:


I select the main entry point, which is the jukebox-api.raml file. Lastly, I click on the “Import” button. And voila, my API is imported, as can be seen in my API overview:


All the resources and methods are available, as expected. You can use the snippets of code to call that API directly, or interact live with the API with the built-in Swagger UI. And if you go back to the “Overview > General information” panel, you’ll be able to access your API definitions in different formats: Swagger 1.2, Swagger 2.0 and RAML 0.8, allowing you to easily translate from one API definition format to another.


Last but not least, although this blog post shows the example with RAML, the multi-file import using zipped API definitions also works with Swagger.