Documenting a REST API with Swagger

REST is now the most common way to expose web services. But how to say to clients how to use a REST API? There’s no real standard or at least de facto standard to expose a REST contract. Many API resorts to a human-readable documentation, which is manually edited and thus hard to keep perfectly synchronized with the API. Another way is to create the documentation from the code itself, and this is what this article covers, by using Swagger on top of Spring MVC.

Sorting out the Swagger components

As explained in the Swagger overview, Swagger has a number of different pieces. Here’s a good time for a quick reminder.

• Swagger spec: The Swagger spec is the official schema about name and element nesting, order, and so on. If you plan on hand-coding the Swagger files, you’ll need to be extremely familiar with the Swagger spec.
• Swagger editor: The Swagger Editor is an online editor that validates your YML-formatted content against the rules of the Swagger spec. YML is a syntax that depends on spaces and nesting. You’ll need to be familiar with YML syntax and the rules of the Swagger spec to be successful here. The Swagger editor will flag errors and give you formatting tips. (Note that the Swagger spec file can be in either JSON or YAML format.)
• Swagger-UI: The Swagger UI is an HTML/CSS/JS framework that parses a JSON or YML file that follows the Swagger spec and generates a navigable UI of the documentation. This is the tool that transforms your spec into the Swagger Petstore-like UI output.
• Swagger-codegen: This utility generates client SDK code for a lot of different platforms (such as Java, JavaScript, Scala, Python, PHP, Ruby, Scala, and more). This client code helps developers integrate your API on a specific platform and provides for more robust implementations that might include more scaling, threading, and other necessary code. An SDK is supportive tooling that helps developers use the REST API.

Swagger

Swagger is a specification for documenting REST API. It specifies the format (URL, method, and representation) to describe REST web services. It provides also tools to generate/compute the documentation from application code. What does this mean? As an application developer, you write web services using your favorite framework, Swagger scans your code and exposes the documentation on some URL. Any client can consume this URL (which comes as XML or JSON documents) and learn how to use your REST web services: which HTTP methods to call on which URL, which input documents to send, which status code to expect, etc.

We’re going to see how to use Swagger on top of Spring MVC, but remember Swagger is a specification and supports a wide range of frameworks.

What’s happening under the hood? Swagger Spring MVC scans the Spring MVC controllers on start-up and registers a documentation controller that exposes the operations the controllers allow. This documentation follows the Swagger specification: any client that understands this specification can use the API. The good news is the documentation is based on the code itself: any change to the code is reflected on the documentation, no need to maintain an external document. Swagger Spring MVC uses Spring MVC annotations to compute the documentation, but it also understands Swagger annotations. 

There are 2 parts in this documentation: the operations and the models. A client can send URL to GET on URL to select needed fields. This is an example of an operation. We see this operation returns a collection of contacts. A client can learn more about this model in the models section. Note the Contact model, which is used by the PUT and POST operations (not shown above). All of this is scanned from the controller and generating API document. let’s see now how to consume this documentation, first from a programmatic client, and second from a neat user interface.

Swagger UI

Have you ever used a written-by-hand web service documentation which isn’t up-to-date? I guess we’re all familiar with that. The API developers are busy writing the API, they don’t have time or forget to update the documentation, and the API client developers are trying to figure out how to use the API, but the documentation is broken or obsolete. Nobody is happy.

Imagine now the developers that write client applications can consult a beautiful UI that tells them how to use the API. The UI even tells them what kind of documents the API expects. This UI exists and is called Swagger UI just expects a URL that leads to a Swagger-compliant documentation. It then uses the documentation to display all the operations. Swagger UI also inspects the models, so finding out about the structure of the JSON documents the API expects is very straightforward.

Conclusion

It is the time to wrap up. Swagger is a powerful tool for documenting RESTful APIs, and by implementing custom extensions, tools, and templates, you can gain more options and more control over the format and content of your Swagger-generated documentation. Extending Swagger's capabilities can allow you to include more API-specific details, specify HTTP requests and responses, and output your documentation as HTML so both developers and API consumers can read it. We can do many things for all of your QA needs: - Ceymplon QA Consultancy