Documentation will set you free. Whether your API is for internal, private use, or for extensive public interaction, proper documentation can make or break an API. It’s not just a tool for developers, either — proper API documentation can drive API adoption more than any other tool within the API provider’s grasp.

In this piece, we’re going to discuss three of the most popular API documentation and specification formats — OpenAPI Specification (Swagger), RAML, and API Blueprint — and address how properly utilizing them can lead to intense and continuous growth. We’ll briefly discuss some alternatives — WADL and Slate — and how they fit into the API documentation space. We’ll touch on the strengths and weaknesses of each format, as well as some general caveats to be aware of when adopting a new documentation method. Finally, we’ll provide some real-use applications of these specifications in code form.

OpenAPI Specification

Of the many API documentation and specification formats, OpenAPI Specification (previously Swagger) is certainly one of the most popular. To call Swagger a “documentation” or “specification” format, however, is somewhat misleading. Developed by Reverb Technologies to be a specification and complete framework implementation, Swagger is used both to generate API server code, client code, and the documentation for those services.

Swagger’s entire focus is on streamlining and synchronizing the update workflow. Because the server and client code is generated and documented at the same time, they can be updated simultaneously. The server code is closely integrated with the documentation methodology, allowing for clean, usable, and understandable documentation.

One of the few caveats of Swagger is the fact that it’s language-agnostic. On the surface, this seems like a good thing — after all, having a broad base of functionality and usefulness is generally positive.

Unfortunately, being language-agnostic limits its value as a broad-base documentation framework when compared with more language-specific or language-supporting frameworks, and can make the process of identifying compatible third party APIs or server-based extensions and solutions that much harder.

Accordingly, a few developers have implemented language specific derivations of the Swagger documentation framework, supporting Scala, HTML5, Java, Actionscript 3, and others.

Using Swagger

Swagger documentation is relatively straightforward — once the endpoint is set, operation documentation is strictly a matter of utilizing the @ApiOperation and @ApiParam annotations to define functionality and the parameters required to carry out specific operations. First, set the endpoint:

/**
 * REST endpoint
 */
@Api(value = "users", description = "Endpoint for user management")
@Path("/users")
public class UsersEndpoint {
	...
}

And then begin tagging the code with the variable annotations provided:

@GET
@Path("/{userName}")
@Produces(MediaType.APPLICATION_JSON)
@ApiOperation(value = "Returns user details", notes = "Returns a complete list of users details with date of last modification.", response = User.class)
@ApiResponses(value = {
	@ApiResponse(code = 200, message = "Successful retrieval of user detail", response = User.class),
	@ApiResponse(code = 404, message = "User does not exist"),
	@ApiResponse(code = 500, message = "Internal server error")}
)
public Response getUser(@ApiParam(name = "userName", value = "Alphanumeric login to the application", required = true) @PathParam("userName") String userName) {
	...
}

Additional alternative functionality is represented in Swagger quite easily. In the above example, multiple @ApiResponse annotations were nested under the @ApiResponses annotation, allowing documentation to cover a wide variety of possible responses and functionality within the API code. This allows for extended testing of possible responses, as well as laying out a sort of “roadmap” for possible and necessary responses before they are properly integrated.

Similarly, Swagger allows for granular control of model visibility and information provision with the @ApiModel annotation. This annotation, along with @ApiModelProperty, allows you to specifically mark a model class for processing, preventing external information leak while providing adequate documentation:

@ApiModel
public class User {

	private String userName;

	@ApiModelProperty(position = 1, required = true, value = "username containing only lowercase letters or numbers")
	public String getUserName() {
    	return userName;
	}
}

In this example, a String is defined for userName, and an @ApiModelProperty is used to specify the information that will be processed by the documentation engine, while allowing other variables to go undocumented.

Worthy of mention is the fact that Swagger, contrary to many documentation specifications, is designed as a bottom-up specification. Unlike other documentation specifications, which endeavor to explain the behavior formed by the API, Swagger specifies the behavior which affects the API in a bid to create more complex, interlocking systems.

Some may be deterred by the relatively increased complexity of documentation resulting from the increasing complexity of the system. All in all, Swagger’s feature set makes it a very popular choice, indeed, for APIs running across multiple platforms, environments, or revisions.

RAML

RAML is a unique beast in the API documentation field, especially within the context of RESTful architectures. Because of the way RAML is designed, it can support REST API documentation in addition to documentation for APIs that don’t precisely or strictly adhere to REST standards such as those utilizing other design architectures like SOAP and RPC. This makes it a wonderful documentation language for languages that aren’t classically designed, or are designed to take advantage of the extensive modified frameworks available to API developers.

Fundamentally, RAML is still a REST-oriented documentation language. Much like Swagger, RAML is intimately related to YAML, but eschews JSON formatting in favor of YAML style text files, editable by any basic text editor or IDE. RAML is also a top-down specification, meaning that it breaks down the system and explains the behavior of the various sub-components.

RAML can be used in a variety of ways to extend its usefulness; because of how it’s defined and structured, it can be used both as documentation and as long-term planning for an API. The latter aspect makes RAML great for generating mock responses, planning function paths, or even implementing interactive API consoles.

Using RAML

RAML is very simple to use. Like Swagger, which has a required REST endpoint function, RAML requires certain metadata:

title: API1
baseUri: https://api.provider.com
protocols: [ HTTP, HTTPS ]
mediaType: application/json

By explicitly stating the above, we’re doing a few things. First, we’re establishing the title value and the baseUri as a means to identify the API being documented. This creates a “trackback” of sorts. Then, by defining the protocols and mediaType annotations, we’re specifying exactly the type of data that should be expected by the API developer or the user reviewing the API documentation.

We can then begin expressly describing the layout of the API itself. This format is unique to RAML, and is one of the many reasons it has become very popular.

/userrecords:
	get:
		description: Retrieve record of users
	post:
			description: Create new user record
	/{isrc}:
		uriParameters: 
      id:
        description: Internal record number for user IDs
		type: string
		pattern: ^[a-zA-Z]{2}\-[0-9a-zA-Z]{3}\-\d{2}\-\d{5}$
		get:
			description: Retrieve user record by ID
		put:
			description: Update record by ID	
		delete:
			description: Delete this ID

Contrary to Swagger, which explains the functionality of an API through models and submodels, RAML specifically annotates and describes function methodology through nested resources and sub-resources. This, aesthetically, is far more oriented towards hierarchical function understanding than simple “cause and effect” understanding.

We can similarly state the response expectations and formation request standards using schema:

/userrecords:
	/{id}:		
		get:
			description: Retrieve user record by ID
		responses:
       200:
         body:
           application/json:
             schema: |
               { 	"$schema": "https://json-schema.org/schema",
                 	"type": "object",
                 	"description": “User ID",
                 	"properties": {                    
										"ID": { "type": "string" },
									"required": [ "id", “user” ]
                }
				example: |
                { "id": "90210",
									"id": "90210",
									"user": msmitts
                }
}

Forgoing the complexity inherent in JSON formatting (which can be largely negated using an application which handles JSON format specifically), RAML is very much a hierarchical style format, which is one of the many reasons it is such an excellent planning tool. By visualizing the cause and effect of requests to the API, as well as documenting specific examples of what return can be expected, APIs can either be documented or planned with incredible granularity.

API Blueprint

So far, we’ve addressed two different styles of documentation that are largely two sides of the same coin — whereas RAML is strictly YAML in representation, Swagger is JSON with YAML compatibility. API Blueprint eschews this, however, with a dependence on Markdown as its format.

Like RAML, API Blueprint is a top-down specification. Whereas Swagger calls resources ‘operations’, API Blueprint describes them as ‘actions’. Unlike both RAML and Swagger, it requires third party server code, as it does not specify any of its own.

Additionally, where RAML and Swagger are both utilizing Java and js to parse, API Blueprint specifically focuses on C++ through Node.js and C# implementations.

The main drawback? API Blueprint lacks advanced construct and code level tooling. Because of this, its adoption has been slow, dwarfed when compared to Swagger or RAML.

Using API Blueprint

Just as with any documentation specification, the name and metadata must first be established, which can be done simply with:

FORMAT: 1A

# Polls

Polls is a simple API allowing consumers to view polls and vote in them.

Resource groups and nested resources are then defined in plain text markdown:

# Group Questions

Resources related to questions in the API.

## Question Collection [/questions]

Actions upon resources or resource groups can then be stated within those headings:

### List All Questions [GET]

We can see that API Blueprint is perhaps the easiest for newcomers to understand. Anybody who has ever written online, be it for a client or personal blog, likely has at least some basic Markdown experience — it’s instantly easy to understand and to read.

Summation – Pros and Cons

So what is an API provider to do? With such great options, what does the choice come down to? From our study we can state the following objectively about these three API documentation specifications:

Swagger

• Pros: Heavily adopted, large community of users and supporters, greater support for multiple languages
• Cons: Lacks advanced constructs for metadata

RAML

• Pros: Supports advanced constructs, decent adoption, human readable format, high industry backing
• Cons: Lacks code-level tooling, still unproven long-term

API Blueprint

• Pros: Easy to understand, simple to write
• Cons: Low adoption, lacks advanced constructs in general, complex installation

The argument comes down to how you want to present your API documentation to your API developer users. Is readability most important? Is modern documentation and forward-thinking specification important? Do you care about adoption rates? These questions, along with their answers in the above pros and cons section, will inform your decision.

Likewise the specific languages and dependencies inherent in your service will be equally as important. If your API is dependent on complex class interactions that have hundreds of subsets and antecedent functions, a specification without advanced constructs is a poor choice, and vice versa.

Alternatives: WADL, Slate, and others

There are, of course, alternatives. Two of the most popular are WADL and Slate. Each have their own caveats, of course.

WADL is incredibly time consuming to create descriptions with, and the linking methodology leaves much to be desired when compared to any of the three specifications discussed throughout this article.

Slate, similarly, has the caveat of having untested or unproven approaches due to the relatively small userbase, despite the fact that it handles documentation much like API Blueprint does, and generates a pretty interface for it all.

These alternatives are interesting, to be sure, but their low adoption rates, issues inherent to their structure, and fundamental caveats make a potentially unstable bet. With many strategies in the modern IT workforce focusing heavily on rapid development and deployment, untested approaches have the distinct possibility of massively lowered quality as the demand rises exponentially.

Conclusion

The methodology one chooses to document is important, but it is important to remember the way the API is designed will largely determine the success of the documentation itself. Think of it like any other language. English is not good simply because it is English — the greater industry of reality TV has shown that English can be equally used to educate and inspire as to push drivel.

Ultimately, the quality of the API will manifest itself in the quality of documentation — it is up to the developer to choose the specification that is appropriate to their work. An ultimately useful and functional API will manifest itself in proper documentation largely because of the amount of effort it takes to create such a well-rounded API; a poorly crafted API will, regardless of specification, almost always result in paired poor documentation.

For instance, with Swagger, SDK generation is baked into the system, with support for programming languages such as Go, Java, Groovy, PHP, Clojure, and more. If developing an SDK for client interaction is your end-goal, Swagger is your best choice. On the other hand, if SDK generation is handled via private or partner applications and methodologies, and larger adoption base is more important to you in the long run, RAML might be the specification of choice.

Resources

A few developers have implemented language specific derivations of the Swagger documentation framework, supporting Scala, HTML5, Java, Actionscript 3, and others. The following resources can help you get started in understanding the various specification formats presented in this piece, as well as some deviations that are worth mention.

• Official Swagger Site
• Official RAML Site
• Official API-Blueprint Site
• Oracle Requirements for Writing Java API Specifications
• enStratus Web Services API Documentation Example
• API-Blueprint Starting Tutorial
• Swagger Datatypes
• readme Documentation Alternative
• Miredot, Java REST API Documentation Alternative

What documentation specification are you using? Why? Reach out to us on Twitter or comment below!