Over a million developers have joined DZone.

API First Approach and API Management With Swagger

DZone's Guide to

API First Approach and API Management With Swagger

Looking for a new API management tool? Read on to see how one team faired while using Swagger's suite of API development tools.

· Integration Zone ·
Free Resource

Over the last year, all the new software components delivered by our software engineering teams have exposed HTTP standard REST APIs. This choice gave us a lot of benefits in terms of modularization and cooperation from an architectural point of view. But, we also had to learn new tools and practices in order to share documentation, design software solutions, and manage the evolution of our services.

We write private APIs (no need to deal with a public API portals or API economies). We also recently decided to adopt an open source solution based on Swagger tooling (I think there’s no need to introduce it or justify the choice in this post, there’s a lot of very well written stuff out there).

This is how we did it.

Swagger Editor (Sketch and Brainstorming)

We used Swagger in the preliminary phase to shape the needs of the team in terms of resources and methods (a great way to force us to think REST compliant). We took advantage of the inline linter, validation, and real-time rendering of a clear and nice graphical representation of our (documented) paths.

It’s a fast and easy tool to improve collaboration and brainstorming with functional analysts, developers, and consultants.

My personal choice for loading it is the Docker image, as I can quickly get as many editors as I want by simply starting new instances on different ports.

When we get a stable outline of our service, we put the YAML files (we prefer this format, more concise) in our ‘definition box’ under version control (Git). The reasoning behind this is straightforward: we wanted to let people know that there is only one official and updated version of the APIs and everyone must refer to it.

Swagger Codegen (Auto-Generated Interfaces and Models)

The Codegen is strongly integrated into our software development process. We use a Maven plugin to regenerate the source code from the YAML files every time we compile our software.

It may seem to be a big constraint but we decided to be flexible where we needed it the most: the business needs. They change over time and we need to deliver as soon as possible, and with a clear pipeline of actions (brainstorming and sketch, design, code, test, deliver) we could keep it under control. Moreover, we have a watchdog: if someone pushes a change in the definition box, our automatic build fails and the development team gets alerted immediately (fail-fast approach).

Last but not the least: we can create a mock implementation of the service and make it available in the staging environment very quickly, thus improving development velocity over more teams.


API versioning can be painful, so we opted for a lighter approach: we use only major versions (v1, v2, …) both in the definition file name (service-def-v1.yaml) and in the service path (http://somewhere.com/service/v1).

The major version is the current version until it is delivered in production or if we need to make minor improvements or fixes. If we face a significant change request or improvement, we move to a new major version. This gives us more flexibility to plan the changes and verify impacts on components who rely on the service involved.

Swagger UI

The integration of the services in the Swagger UI is an effortless task, as the interfaces of the APIs generated by the Codegen are already annotated with all we need to document and try out our components in the UI. This is really cool!

If you want to go deeper, I’ve created some repos on my GitHub account:

  • Swagger plugin PoC. You can find it here; if you’re asking yourself why there’s already a Maven plugin, here’s the answer: we needed some custom Codegen behaviors in order to fit it to our needs; this is not the code running in our production environment but the project I created to check the feasibility of our solution.
  • Here is a simple HTTP server to get the YAML definition files from a local environment.
  • Here is a Spring Boot application with a REST API.

Build and deploy API integrations 7x faster. Try the Cloud Elements 100% RESTful platform for 30 days free. Access your trial here.

swagger ,api management ,maven ,integration ,api development

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}