REST API Documentation Part 2 — Swagger, RAML, and Open API

In my previous article, I promised to look into some of the tooling that is availaible to produce decent enterprise class REST API Documentation. That's the goal of this post.

The REST community for a long time was against having any kind of metadata or description for REST APIs, with the fear of REST getting bloated. However, the need to document and automate APIs for the consumers in a consistent fashion has been a significant ask from the enterprise community. Slowly but surely a prominent tool set for producing professional documentation for REST API are emerging. 

The metadata other than generating the needed documentation is also expected to generate client/ server code, create test harnesses, help production monitoring and also perform real-time request and responses (Live API Experience).

There have been earlier attempts like WADL with similar intentions which failed to gain traction either due to complexity of the specification or vendor specific limitations or lack of available tooling. Emergence of a widely adopted standard would benefit API producers, consumers and different stake holders and would continue to benefit the adoption of REST APIs. 

Swagger

Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. Swagger is language agnostic.  Swagger-enabled API, allows you to get interactive documentation, client SDK generation and discoverability.

The Swagger specification allows you define a set of files to describe an API.  Using these files, the Swagger-UI project could display the API and Swagger-Codegen could generate clients in various languages. 

Swagger UI is a dependency-free collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.

Swagger CodeGen is a template-driven engine to generate client code in different languages using your Swagger documentation.

The Swagger Ecosystem provides support for various tooling built both by external parties and the developers of the Swagger specification.     

Starting January 1st 2016 the Swagger Specification has been donated to to the Open API Initiative (OAI) and has been renamed to the OpenAPI Specification. The Open API specification is backed by the likes of Google, Microsft and IBM.

RAML

RAML is a language for the definition of HTTP-based APIs that embody most or all of the principles of Representational State Transfer (REST). The RAML specification defines an application of the YAML 1.2 specification that provides mechanisms for the definition of practically-RESTful APIs, while providing provisions with which source code generators for client and server source code and comprehensive user documentation can be created.

RAML to HTML is a documentation tool and it outputs a single HTML page console based on a RAML definition. It's written in NodeJS and it can be executed as a command line. The project is an opensource project and could be customized on a need basis. 

RAML is also extremely popular and has a rich ecosystem of tooling built around RAML available.

API Blue Print

API Blueprint is a documentation-oriented web API description language. The API Blueprint is essentially a set of semantic assumptions laid on top of the Markdown syntax used to describe a web API. The format is open sourced and lot of tooling including code generators, editors are provided by APIARY. They also provide a cool way of standing a mock server with which you could experiment.

High Level Comparison

It is important to pick a tool that encompasses the full API Lifecycle. All the three tools mentioned above have a large ecosystem of open source projects or vendor solutions which allows you to design, build, test, document, and share your APIs.

Rather than having different specifications and different tools sets that are built for around each of these specifications, I would like to see a standard specification and different tooling that is built around the standard specification.  This isn't anything new, and this how most of the industry standard specifications emerge with having one winner, picking best practices from many different specifications. 

This is where Swagger really shines with its Open API Initiative (OAI) supported by inustry giants like Microsoft, Google, etc. However, RAML has very good features, and I expect the Open API Initiative to pick some of the best parts from many different specifications as it tries to standardize.

References

1. https://apiblueprint.org/
2. http://swagger.io/http://www.mikestowe.com/2014/07/raml-vs-swagger-vs-api-blueprint.php
3. http://raml.org/
4. http://www.mikestowe.com/2014/07/raml-vs-swagger-vs-api-blueprint.php
5. http://apiux.com/2013/04/09/rest-metadata-formats/
6. http://www.mayerdan.com/programming/2014/01/29/investigating-api-tooling/
7. http://www.slideshare.net/SmartBear_Software/api-strat-2014metadataformatsshort