API First approach with Swagger

1 Comment


Modern IT companies embrace an API (Application programming interface) as an important part of their businesses. Follow the trend and change how you perceive APIs. Build an API before anything else, except business plan (hopefully). Acknowledge the fact that your service will be customer-facing, even if for now the only customer is a web front-end your colleague is working on. Customer-facing, that should ring a bell.


Also accept an API as a first-class citizen for your company instead of an afterthought plugin thing. API is a part of company’s strategy.

In this post, we dive into designing and implementing an API using Swagger, Spring Boot. We also consider API cooperation, maintenance and documentation.

Technology stack

I’ll be using Java and Spring Boot for RESTful API implementation examples. However, most of the content of this post is language/framework agnostic, because of the fact that Swagger supports many different technologies.

API First: Swagger Top-Down approach

There are a lot of good API design tools. Here are some useful comparisons: 12. My weapon of choice is Swagger, mainly because of prior positive experience and a strong community. After all, who would want to see search results below?


Design API with your clients

Let’s get our hands dirty doing something. Open Swagger Editor and start hacking your API’s specification. To do that some basic knowledge of Swagger Specification (OpenAPI Specification) is useful. If API if fairly simple you should be able to do this with little to no specification archeology. Open any example (File -> Open Example) and write by analogy.

Few days later, after long conversations between your team and API clients you come up with the first API draft:

You feel good. You send API clients (Web, iOS, Android, others) the link with the API doc, which comes with integrated stub:


You get first feedbacks and start correcting the API. You end up with API that looks good for everyone:

In the example above there’s only one modification from the first version. It’s /pets/{id} request to get a pet by it’s id.


The next step is to create a usable mock server for your clients to start integrating with the API. That way you get to work in parallel. You also get early feedback and could make API correction while you’re still not too far down the road implementing it.

The tooling options are wide. You can generate a mock server with swagger-codegen tool. With it you can create stub for a wide range of platforms and languages, from Node.js to Scala NancyFX .NET framework (Server-stub-generator-HOWTO).

It’s also possible to generate mock server code directly from Swagger Editor (Generate Server menu).

http://playground.apistudio.io/ also creates a mock server, you can choose the request on documentation screen and click Try this operation.

You can also import your API specification (yaml or json file) to swaggerhub.com. Beware, you can only create a Public API using Free tier. Then add ‘API auto mocking’ integration as described in a doc and you have a basic mock server up and running.

Client library

Now, it’s a good practice to create a client library for your API. No problem, build a skeleton based on the API definition you just developed, you can choose between a number of languages:

  • Use swagger-codegen-cli
  • Or Online Swagger Editor (‘Generate Client’)

It still needs some work to become a smart client, but it’s a good start.

If you need a JavaScript client, consider using swagger-js, dynamic library that doesn’t need any static code generation.


Now, let’s implement the actual business logic behind our newly born API. Let’s generate a skeleton for Spring Boot. As usual, using Swagger Editor or:

You can now start implementing logic. Classes named *Controller.java are the entry point of your REST server. Just don’t forget, no logic in Controllers.

Taking documentation seriously

The path of least resistance

Now, what you’ve got for free is a good looking documentation for your API.

You can use Swagger UI to provide an interactive documentation that would look similar to this demo.

If you’re using Java and Spring Boot as a framework, there’s a great library (springfox) that will take care of dynamic documentation generation, no need to to download, run and configure a separate Swagger UI.

Boot to Fox

Let’s instrument your Spring Boot application with a shiny dynamic API documentation. First, the dependencies.

Next, the configuration. In springfox terms, you build the documentation using a Docket.

What happened here? We just created a swagger documentation. Endpoints will be searched under ‘com.petstore’ package and lower. The “Try this operation” button will send requests to “localhost:8080”.

Let’s also configure the redirection to swagger-ui html. Not required, but handy.


That’s it. Run the application and go to http://localhost:8080/ (change to whatever port you have).

If you need a API specification in a raw format, visit http://localhost:8080/v2/api-docs to get a JSON. Useful after API modifications. You can use that JSON to create mocks, host API documentation or any other purpose.

Tip: convert JSON specification to Yaml using Swagger Editor (File -> Paste JSON).

You will see your API documentation, generated from your current API (as described @RequestMapping, @ApiOperation and other Spring and Swagger annotations). No generation step needed.

There are much more features there I’m not touching for brevity’s sake. For example, if you’ll throw in admin API to your app, it’s wise not to provide access to it’s documentation. Separate open and admin APIs and use “.groupName” docket method to name them.

Make it pretty

If you would like to customise Swagger UI page (shiny new logo, your site’s colours) you can host your own copy and customise the look of it.

I would presume you have a docker installed on the server that you want to host the documentation. Let’s do it.

Now you should be able to access it via http://<your_host>/ . Sweet!

For the customisations, the very least you would want to change

to something like

That will make Swagger-UI to load your API documentation immediately.

‘Want cool-new-responsive-material docs? You could take this pretty Swagger-UI fork for a spin. Or not.

BTW, I just realised we had no pictures for about 2,669 words.

API Corrections

One thing is certain about your API is that it’ll need to evolve. You could import your API specification to the editor and edit it, then generate scaffolding again and merge to the existing code. I wouldn’t suggest it unless the API rework is really big, and maybe not even then. You better off modifying API in the one place where there is no lie, code.

Add or modify Spring Boot’s @Controller-s and @RequestMapping-s. Swagger gets most of the API info from those standards annotations and request methods signatures. Others, like @ApiOperation and @ApiResponse, will swiftly start making sense.

In the process of modifications, as you grasp swagger’s semantics and annotations, you’ll probably also clean up the generated code. Generated code is a source of some evil.

Security checks, tools

If you’ll check other Swagger Tools the power of using mainstream tooling becomes obvious. Some of the tools are expensive, but some you can use freely for a small projects. For example, you can use Rest Secured to check your API for common security vulnerabilities.


There are a lot of reasons to take API seriously. Whether it’s purpose is internal systems communication or a public-facing interface, it pays off to design an API as any important thing, with a good forethought.

With an API, as with any software solution, maintenance cost is prevailing in overall cost. That’s the main reason to choose tooling carefully, consider and research choices. Better yet, to get hands dirty prototyping.

Swagger ecosystem provides a wide variety of choices and a huge community. I’d definitely recommend to give it try.


It's over, go home

Share if you liked it.
Categories: API Tags: Tags: , , , , ,