Document your RAML and Open API definitions with API Console v6

February 12 2020

0 comments

I am happy to announce that a new version of API Console is now available. It brings multiple changes and new tooling. Read more to learn what’s new in this release.

API Console is an application to automatically generates documentation for an API from a RAML or Open API definition. It is done by generating an AMF data model thanks to the AMF parser or the “webapi-parser” module. The console is built on top of web platform APIs so it can be easily integrated with every web-based application. It comes in two flavors: a stand-alone application and a web component. Depending on your use case, you may use either of them.

The stand-alone application allow you to quickly generate documentation for an API and run it on a web server as a separate application. We are providing a CLI tool to generate the application from sources and a Docker image to simplify the deployment. The web component is to be used if you want to integrate the console with an existing application. This requires more setup and development process but allows for the most flexibility.

What’s new in version 6?

API Console is now WCAG compliant. During the development process we made sure that the console is accessible for users with disabilities. This version is tested via automated software and via manual testing.

The updated UI implements changes requested by our customers and the community. The navigation has a slightly different structure and now renders a full path to the resource, even when it exceeds the size of a single line menu item. New examples and annotation widgets makes the UI more user friendly.

The request editor (aka “try it”) has been redesigned to simplify interaction with the API. It now only renders fields that require input from the user to make a successful request. This means, for example, if headers are not defined for an operation then they are not rendered.

With this release we added more security by sanitizing markdown data that are being rendered. Also, user input in the request editor is tested against invalid data.

Improvements to the console

Most improvements are related to performance. The size of the bundle has been reduced almost four times and now the bundled API Console weight is ~300KB. This speeds up console rendering time and improves memory footprint.

In the documentation view, complex types are now hidden by default. This reduces potential crashes when the documentation has huge type declarations. In previous versions of the console this would lead to tabs crashing. Similarly, huge examples generated for such types are not highlighted by default. Previously it would require the browser to render unreasonable amount of markup that would hang the tab for minutes.

The console’s source has been rewritten to use the latest web standards which puts most of the work to the browser instead of JavaScript. This improves overall experience as the console runs smoothly regardless of the size of the API. The console still works with legacy browsers (down to IE11) with polyfills generated with the bundle.

Developer improvements

Being as close to standards as possible was rule #1 when designing architecture for API Console and the build tools. The console now follows Open WC standards for development and building processes. Application-specific code related to the development and building process has been reduced to the minimum.

API Console has its own node module and CLI command to generate a bundle in a CI environment or manually. With this release, we offer a Docker image that has bundled API Console, AMF parser, and a web server with it. Developers just need to pass an API project to generate data model from it and run the image on your Kubernetes instance.

Reasons to choose API Console

API Console is and will be in active development as it is one of the core Anypoint Platform products while being an open source project. The console is tested in an enterprise environment and runs in both public and private clouds. It fulfills all requirements for an application to run in government’s cloud.

We have experience with building API documentation products supported by several years of development of API Console and other products like Advanced REST Client. We are open to suggestions and over the years we have listened to the voice of the community and our customers. Today, we are proud of the final effect of our work and happy to share this experience with the community.

How to get started?

We’ve prepared a few demos with basic use cases for API Console. You can check it out at demo.api-console.io. For developers we have prepared a documentation page at docs.api-console.io.

Try API Console today and give us your feedback. We accept issue reports and feature requests on console’s GitHub page. If you are MuleSoft customer you can contact customer support and gives us your feedback directly.



We'd love to hear your opinion on this post