Validation of RESTful (Swagger) Documentation

Documenting an API is probably the most important part after creating it. After all, without good documentation an API is - useless. At Kenshoo we've chosen Swagger 2 to document our RESTful APIs.

About Swagger

The goal of Swagger™ is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via Swagger, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, Swagger removes the guesswork in calling the service. Swagger Spec defines the specification. Swagger Editor provides a convenient web editor to edit and preview the documentation, and also some convenient examples to get started. Swagger UI visualizes the documentation as a human readable web page.

With Swagger 2 the API descriptor is kept in a single yaml file:

But how can we validate that our documentation is accurate and matches the actual code?

The question becomes even more important as time passes and code evolves. 

Do resources still exist? Were paths changed? Maybe properties were renamed?

One way of solving these issues would be to regenerate the documentation from code. But as we strongly believe in a "design first" approach - i.e. that documentation should be created before code - we looked for a different path, one that could allow us to write the documentation first, and then verify the code matches our design.

Swagger-validator is a new component we're open sourcing at Kenshoo, that aims to help verify that the documentation of an API matches the actual code.

In order to use it, all the developer needs to do is map the paths and definitions of the yaml file to the Java classes. 

For example:

As you can see under each path a new custom element x-javaClass was added. It contains the fully qualified Java class name.

And that's all!

The validator can now run the necessary checks, throwing a meaningful exception if anything fails.

The validator can be activated as any other JVM process (be it Java, Scala, or Groovy), but the easiest way to run it is probably via a simple unit test:

So what's validated?

Resources are validated against their paths, using the @Path annotations their operations (GET, POST, etc.) have

Objects (definitions) are validated against the properties they carry - matching properties to object fields.

The current implementation uses Java 7.

The resources are validated with Jax-RS annotations.

The definitions are validated as POJOs.