Here is to establishing the perfect collaboration between backend developers and frontend developers!
Are you a backend developer?
If you’re a backend developer, I’m pretty sure you have experienced difficulties with cooperation during the development of a full stack software.
You always need to team up with many people and as the process progresses, the guys from the other side (I don’t mean the dark one, but the client) are eager to give your APIs a try. These clients may realize that, for whatever reason, you haven’t finished these APIs yet. However, the team needs to move on, so we need a tool that helps us out here.
And this is how we get acquainted with the world’s most popular framework for APIs: Swagger.
No, it’s not another hipster tech gadget. It is a simple yet powerful representation of your RESTful API – and it’s open source. With a Swagger-enabled API, backend developers get interactive documentation, client SDK generation, and discoverability.
So what can I do with it?
…you might ask.
As an API provider you have several approaches to begin with:
- The top-down approach is where you’d use their very own editor to create your Swagger definition (with the help of the popular YAML or JSON... btw, we are working on a YAML how-to post, so keep an eye out!). This approach entails an API design-first workflow. Then, you can use the Swagger Codegen to generate server/client implementation.
But remember(!): the Swagger definition is the soul of the whole ecosystem of tools provided by our beloved Swagger.
- Or: you can do it the other way around with the so-called bottom-up approach, where you already have an existing API for which you create a Swagger definition. You just have to use one of the supported frameworks, add annotations to your code, and generate the definition.
On the other hand, as an API consumer who wants to explore the interface, there is a dependency-free collection of HTML, JS and CSS assets that dynamically generate beautiful documentation for you (Swagger UI). You even have a chance to try them out – pretty cool, isn’t it?
Now, let’s peek into the specification!
The API specification
The previously mentioned Swagger Editor provides some examples, so you quickly get a sense of how it’s supposed to be done.
As you can see the Swagger representation of the API is made of a single file. Most of the fields are pretty straightforward, so I’ll just pick a few to introduce in detail.
The root object requires three mandatory fields: the swagger version, the info and the paths object. The first must be ‘2.0’ as we are using the version 2.0 now. The info object provides metadata about the API, it’s mainly for clients. The paths describes the available paths and operations for the given API.
The paths contains the parameters object, where one can define a list of parameters that are applicable for the API. There are five parameter types (in field):
- path: parameters that are actually part of the URL (ie. in /sysuser/:id, the path parameter is id)
- query: parameters that are appended to the URL (ie. /sysuser?id=123, the query parameter is id)
- body: payload that is appended to the HTTP request
- form: same as body, but used when content type of the request either application/x-www-form-urlencoded or multipart/form-data
- header: custom headers that are appended to the HTTP request
So, you can reference your models in the responses object. The definitions object holds data types produced and consumed by operations.
And finally, the corresponding request looks like this:
If you’d like to dig in deeper, I suggest you visit Swagger’s GitHub wiki; you’ll find very detailed and neat documentation.
If you already have a bunch of code at hand, you do not want to mess around with the editor to write your API again.
The easiest way to solve this is to add a set of annotations to your classes so you can generate the specification automatically. Swagger supports the most frequently used frameworks: Spring MVC, JAX-RS, Node.js or Play.
The annotations are grouped into three groups – the annotation to declare the resource, the set of annotations to declare an operation, and the set of annotations that declare API models.
Let me show you an example of how this works in the Play Framework.
For all the details, please follow this link.
Backend developers’ conclusion
I think I speak not only for myself but for the majority of developers when I say the cooperation can be a pain in the *ss if the API isn’t specified well in the early stages of a project.
You can, of course, simultaneously write your documentation with the code. But why would you do the same job twice? Use Swagger for your – and your team’s – own sake!