Tuesday, December 3, 2013

A RAML / APIHub Plugin for SoapUI

RAML is a relatively new REST API documentation/metadata initiative backed by a workgroup with representation from MuleSoft, Intuit, Box, PayPal, and others. It is similar to initiatives like swagger, api-blueprint, WADL (to name a few) but with some unique twists of its own. RAMLs adoption and eco-system of tools is growing continuously so it seemed like a good (and fun) idea to create a plugin for SoapUI that allows you import RAML files into SoapUI for testing of its defined APIs.

Since the core model of all these REST metadata formats is very similar (resources, actions/methods, query/header/path parameters, representations, etc) - creating the plugin was rather straight-forward given that SoapUI already has pretty solid REST service and testing support. RAML itself uses YAML and comes with a java-parser which can be used to parse RAML files and resolve the described API model - the plugin uses this to resolve and traverse RAML files and create corresponding SoapUI objects.

Since Mulesoft also runs the APIHub API directory - integrating that with SoapUI seemed like a nice idea as well (similar to the ProgrammableWeb Plugin) - and since the APIHub API exposes both RAML and Swagger definitions for its APIs - integrating this plugin with the SoapUI Swagger Plugin makes for an integrated experience, allowing you to:
- Browse the APIHub directory for APIs that have either RAML or swagger definitions
- Import these into SoapUI for functional testing, load-testing, security testing, monitoring, etc.

I won't dwell on RAML itself here - I recommend you have a look at the RAML website and specification. The plugin itself is mainly written in groovy and pretty straightforward, have a look at the GitHub repo for more information on how to build it with maven, etc.

Now, let's dive straight in!

Getting Started

Make sure you have installed either SoapUI 4.5.x or 4.6.2 (or later, 4.6.0 and 4.6.1 had a REST related bug that is now fixed), download the plugin distribution from sourceforge and unzip it into your soapui/bin folder (if you're on a Mac this is under <SoapUI>.app/Contents/Resources/app). If you want to enable swagger support for the ApiHub directory install the swagger-plugin in the same way (download from sourceforge) - the resulting ext and plugins folders should contain the following files:

(the ext folder)

 (the plugins folder)

Now when you start SoapUI you should get the following entries in the soapui log tab at the bottom of the window:

Create a new empty SoapUI project or open an existing one and right-click on the project node; the popup menu should contain the following menu options:

Importing RAML definitions

Selecting the "Import RAML definition" option will open a standard file/URL prompt:

specify a local or remote RAML definition and press OK - it will get imported into SoapUI as a REST Service, allowing you to invoke the API using standard SoapUI REST functionality. For example, below is the service you get when importing the twitter RAML file available at http://www.apihub.com/twitter/api/twitter-rest-api/twitter-rest-api.raml.

Now you're all set to starting testing the imported API - check out the documentation at soapui.org if you need some assistance with getting started.

Importing APIs from APIHub for testing

If you're keen on integrating or testing one of the APIs available in the APIHub directory, the "Add API from ApiHub" menu option is what you need. Selecting it from the project popup opens the following dialog:

The list contains all APIs at APIHub that have RAML definitions - if you have installed the swagger plugin as mentioned above you will see those that have swagger definitions as well (as shown in the screenshot). Select an API and select OK to import it into SoapUI for testing - for example the FitBit API selected in the above screenshot imports as follows:


One of the major shortcomings in SoapUI is its lack of built in support for OAuth 1/2. Thus, when importing a RAML definition that includes security schemes for OAuth, these will simply be ignored - requiring you to manually add access tokens or credential information to your requests. Another shortcoming is SoapUIs lack of JSON Schema support - any schemas defined in the RAML will currently be ignored.

Next Steps

A natural next step would be to allow exporting of RAML definitions for any REST service defined in SoapUI - which would basically allow you to generate RAML files for existing REST services or those imported from other formats that are currently supported (WADL and Swagger for now). Of course you can also define a REST Service in SoapUI manually by creating resources, methods, adding parameters, etc.

Ultimately though it's up to the users of the plugin to request new features - please don't hesitate to do so at the plugins GitHub page (where you will find more info on building, installing, etc).

Have fun!



  1. It works! Amazing! Congratulations Ole!

  2. Great! Please don't hesitate to comment with any feedback / issues / suggestions - thank you!


  3. is there a way to use this SoapUI RAML plugin with the SoapUI Maven plugin ?

    1. Hi Dmitry,

      hmm... no, not really - what use case were you thinking of ?



  4. Hi ,

    I added the RAML plugin jar to my SOAP UI bin\ext folder and can see the statement below in the SOAP UI log :
    Sat May 03 23:17:41 IST 2014:INFO:Adding [C:\Program Files (x86)\SmartBear\SoapUI-5.0.0\bin\ext\soapui-raml-plugin-0.3-plugin.jar] to extensions classpath

    However on right clicking a project I do not see the option to Import RAML definition.

    What could I be doing wrong here ?


  5. Hi,

    you need to put the plugin-jar in the \bin\plugins folder instead (create this folder if you don't have it...)

    Hope this helps!


    1. Thanks that works. I probably should have unzipped the plugin in the bin folder.

    2. Great - let me know if you have any issues - have fun!


  6. I am trying import RAML definition from my disk and i get resource not found error on my external schema files that are on the same folder. I found this issue in github https://github.com/olensmar/soapui-raml-plugin/issues/5 but i could not download the patch i am not sure if version i have supports !include.

  7. I've imported RAML definition (see http://raml.org/docs-200.html) and it lost response examples. should It works?

  8. Hi,

    if you select to create a Mock/Virt service when you import the RAML you should see the example responses in the corresponding Virt response messages.

    hope that helps!


  9. When trying to update from RAML definition I always get the error message like below and no update is done although the file traits/security-1_0.yaml is in the corresponding location.
    I'm using Ready! API 1.1.0

    Fri Dec 12 14:32:34 CET 2014:ERROR:An error occurred [resource not found: traits/security-1_0.yaml], see error log for details

  10. Hi,
    When trying to import a RAML into SOAPUI, it does not seem to work all the time
    Even if I have a correct RAML, SOAPUI does not create the mock service consistently...
    I have not figured out what makes it work or no but am happy to send you samples if you want to try

    1. Hi!

      I'm sorry for the late response - please open an issue on GitHub (https://github.com/olensmar/soapui-raml-plugin/issues) so we can sort this out - thank you!


  11. Hi , I am using, when I start soapUI , I can see the entries in the soapui log which I added on ...\bin\ext and ...\bin\plugins

    but when I right-click on the project node, I can't see "Import Raml Definition" .

    Any idea?Thank you very much.