Since APIs are designed to be consumed, it is important to make sure that the client, or consumer, can quickly implement your API and understand what is happening. As you build out your API you want to ensure that you not only provide informational API documentation to help developers integrate/debug connections but also return relevant data whenever a user makes a call — especially a call that fails.

Good quality documentation is essential to developer experience, which in turn will impact the adoption and long-term success of an API.

In this article, I am going to introduce a few tools which help with designing, testing and documenting APIs.

Swagger

Swagger is a complete framework for describing, producing, consuming, and visualizing RESTful web services.

This tool is probably the most well-known of them all for documenting Rest APIs - it's basically a REST API ecosystem consisting of several aspects. You can document APIs with JSON using the Swagger spec, and use the Web UI to dynamically convert it into API documentation in a web page.

I've used Swagger with a Java library called Springfox which is designed to generate a Swagger spec from APIs built using the Spring framework. It is straightforward to integrate Springfox into Spring and uses the Spring REST annotations to generate the docs, which are already present in your code.

Swagger is free to use, licensed under the Apache 2.0 License and you can find all Swagger related tools under their website.

RAML

RAML (RESTful API Modeling Language) provides a structured, unambiguous format for describing a RESTful API. Like Swagger, once you create a RAML file that describes your API, it can be consumed by different platforms to parse and display the information in attractive outputs. It is free to use, licensed under the Apache 2.0 License.

There are some sophisticated tools for the API design:

API Designer - A web-based API development tool that allows API providers to design their API quickly, efficiently, and consistently, and socialize the design. It consists of a RAML editor side-by-side with an embedded RAML console (the API Console).

API Console - A graphical user interface for a RAML-defined API that visually exposes the API's structure and important patterns and serves as interactive API documentation.

API Notebook - A web-based, persistent, JavaScript scripting workspace that enables live testing and exploring of APIs, and saving API use cases as markdown gist. It can generate an API client based on a RAML API definition, and through it performs authenticated live calls on a real server or on just an empty API interface.

Spring REST Docs

Spring REST Docs generates documentation for RESTful services that is both accurate and readable. Like Springfox, it is Spring REST annotation aware and will generate API documentation, in Asciidoctor format, for any class annotated with @RestController.

Spring REST Docs can be created using the Spring MVC Test framework to make requests to the REST services which are to be documented. This produces documentation snippets for the request and the resulting response.

Enunciate

Enunciate is an engine for enhancing your Java Web service API. Some of the features are:

• Full HTML documentation of your services, scraped from your JavaDocs.
• Client-side libraries (e.g. Java, .NET, iOS, Ruby, JavaScript, GWT, etc.) for developers who want to use your API.
• Interface Definition Documents (e.g. WSDL, WADL, XML-Schema, etc.).

It is an open-source project, licensed under the Apache 2.0 License.

I have just covered some of the tools in this article- there are many others available or in development, and new ones are popping up continuously. Let me know in the comments if you've tried a solution that you'd recommend to others!