RAML And OAS Support In API Console

Last year the CTO of MuleSoft, Uri Sarid, announced that the company is joining the Open API Initiative of the Linux Foundation. This extended MuleSoft’s investment in open specs (RAML) and open source API tooling to also embrace the Open API specification (OAS), as part of its investment in modeling any domain via the Anything Modeling Language (AML) and the open source AML Modeling Framework (AMF). AMF provides automatic interoperability between RAML, which is optimized for modeling HTTP APIs, and OAS, which is a ubiquitous description format for HTTP APIs.

Today I am proud to announce that MuleSoft’s open source API console now supports both RAML and OAS to automatically generate API documentation. This is a part of initiative we started a year ago to add OAS support to Anypoint Platform. Now you can use best in class API documentation tool without worrying about technicalities like API specification format.

This is possible thanks to AML (Anything Modeling Language) and related AMF (AML Modeling Framework). AMF allows to parse RAML and OAS files and produces common data model which is then used in API console to generate the view.

API console comes as a standalone web application and as a set of web components that are highly embeddable in any web environment. This web components — the API components — are open source and can be used to embed API documentation into your existing web page without any limitations. Theming system based on CSS variables allows to style API console according to organization’s corporate style guide. Our developer build tools helps developers to create production ready bundles so the API console can be used across all browsers and web environments. Finally world class design and convenient request editor allows your customers experience the API and learn your products faster.

See our demo page for Google Drive API at https://mulesoft.github.io/api-console/

Build an API portal from your API specification

It is very easy to build an API portal thanks to our CLI tool (Command Line Interface). This section demonstrates how to build an API portal with just few command line commands.

First make sure you have Node.js installed. Open you terminal and type

node --version

This should output something like:

pawel@pawel-pc:~$ node --version
v8.11.2

If it says that the program cannot be found then you have to install Node.js on your machine. To do this follow instructions from https://nodejs.org/en/download/

The next step is to install our CLI tool (no need for sudo command when using Windows)

sudo npm i -g api-console-cli

After few seconds the CLI tool is installed and we can build an API portal. Navigate to your API directory

cd location/of/api

Now run the build command to generate the API. The tool supports build command that has several options. Run api-console build --help to see description for all of them. The most important are:

• -a the location of the API main file
• -t type of the API spec format, it can be RAML 0.8, RAML 1.0, OAS 2.0, or OAS 3.0 (currently in beta)
• -o where to put the result, default to build folder in current directory

Run the final command replacing parameters with your API file name and the type.

api-console build -a api.raml -t "RAML 1.0" -o api-portal

It may take about a minute to build the console. If you run into trouble caused by reaching memory limit, add NODE_OPTIONS=--max_old_space_size=2048 prefix to the command (MacOS, Linux) or set NODE_OPTIONS=--max_old_space_size=2048 on Windows. This prefix sets memory limit for node process to 2GB.

When ready run api-console serve command to see your portal

api-console serve --open api-portal

The --open argument tells the program to open the portal in the default browser.

That’s it! You can now copy generated files to your server and use them to publish your API portal. If you need more advanced build options (like in continuous integration pipeline) you can use our npm module to perform the build.

It is also possible to generate the API Console as a web component and use it to embed API documentation into existing web page. Refer to our docs for more information.

We are happy to hear from you about your experience with API Console and our build tools. Leave us comment, create issue report at mulesoft/api-console repository page or email us at api-console@mulesoft.com.