Over a million developers have joined DZone.

API-First With Swagger

DZone's Guide to

API-First With Swagger

Learn about what API First design means and how to define and implement an API using Swagger, which is based on the OpenAPI specification.

· Integration Zone ·
Free Resource

How to Transform Your Business in the Digital Age: Learn how organizations are re-architecting their integration strategy with data-driven app integration for true digital transformation.

With the birth of new channels and interconnected devices (web, mobile, IoT...) the use of RESTful APIs has become fundamental, and the API First Design can be a winning strategy.

The three basic principles of API First are:

  • The API comes before the user interface. Before you develop your web application, mobile, IoT, etc, you'll need to define your APIs, and then work on the channels that will use them.
  • The API comes before its implementation. By using tools such as Swagger to define and describe interfaces, you are generating discussions with the customer, user story and, mocking the APIs, also a user interface.
  • The API must be described or self-descriptive. API documentation is an indispensable requirement for making it usable by humans.

This post will define and implement an API using Swagger. 


There are other API design tools, e.g. apiblueprint and apiary, the choice is due to my positive experience with Swagger and the fact that it is based on the standard OpenAPI Specification (OAS).

Design the API

Open the Swagger Online Editor. Using the example provided, "Swagger Petstore," it should not be complicated to draw your own API, however, reading the specification may be helpful.


Generate the Mock Server

The second step is to create a mock server so that the API consumers can start integrating it. This operation allows you to work in parallel and receive feedback before you begin the implementation.

The mock server can be created directly by using the online editor and choosing your preferred technology:image3

Another way is using the cloud service Swaggerhub.

Generate the API Client

Another interesting feature provided by the editor is to create the client stub by choosing from different languages: image1

Below are some of the supported technologies: ActionScript, Ada, Apex, Bash, C# (.net 2.0, 4.0 or later), C++ (cpprest, Qt5, Tizen), Clojure, Dart, Elixir, Eiffel, Go, Groovy, Haskell, Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx), Kotlin, Lua, Node.js (ES5, ES6, AngularJS with Google Closure Compiler annotations) Objective-C, Perl, PHP, PowerShell, Python, R, Ruby, Rust, Scala, Swift (2.x, 3.x, 4.x), and Typescript (Angular1.x, Angular2.x, Fetch, jQuery, Node).

Develop the Implementation

The last step is to develop the business logic. Just as we previously created the mock server, we create the implementation skeleton choosing the technology we will use for the deployment.

The Swagger codegen supports many different technologies: C# (ASP.NET Core, NancyFx), C++ (Pistache, Restbed), Erlang, Go, Haskell, Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy, Play Framework), PHP (Lumen, Slim, Silex, Symfony, Zend Expressive), Python (Flask), NodeJS, Ruby (Sinatra, Rails5), and Scala (Finch, Scalatra).

Swagger UI

Swagger UI provides a web interface to read the documentation and interact with APIs. You can get an idea by looking at this demo.image4

Also, if you use Spring Boot, you can use springfox to integrate the documentation directly into the source code and generate the human-readable version in a dynamic way. springfox


Nowadays, many companies are oriented towards the architecture of microservices, and the API-First design is well-matched with this trend allowing parallel development, with the agile teams.

The second part of this article is “API-First With Jhipster” and is a work in progress.

Make your mark on the industry’s leading annual report. Fill out the State of API Integration 2019 Survey and receive $25 to the Cloud Elements store.

api ,swagger ,openapi ,integration

Opinions expressed by DZone contributors are their own.

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

{{ parent.tldr }}

{{ parent.urlSource.name }}