End to End Restful API development using OpenAPI Specification

Ramesh Lingappan
The Startup
Published in
7 min readOct 23, 2019

Image downloaded from the internet

With the increasing number of adoption towards service-oriented architecture and for better integrations with external systems, it became a necessity to write Restful APIs for our services. While building so we might often find several challenges such as,

  • Standard & Consistent API design
  • Better documentation
  • Client Libraries
  • Playground (better developer experience)

So while writing APIs, we have to make sure it sticks to a standard design principle, update documentation (hosted elsewhere) and finally write client libraries (harder if you have to support multiple languages). Doing all of this manually is a painful job.

Likely we have OpenAPI Specification (formerly known as swagger), which offers us a standard, language-agnostic interface to write RESTful APIs which allows both humans and computers to understand the service capabilities.

You can read more about it, there are plenty of content out there, here is the official site,

In short, you can define the APIs in a JSON or YAML file, which can be easily converted to code or documentation.

In this article, we will be looking at how we can work with OpenAPI specification, generate code and use it in the server & client-side.

Setting up:

For this example, we will be using java & gradle , but the idea is the same for other languages or environments. First, create a Gradle Java project petstore-api from the IDE of your choice, I use IntelliJ, Gradle 5.

A plain simple java project, you can also remove the java source folder from the project, since we are not going to write any code :). This project serves as a commonplace to hold the API contract (only…

Ramesh Lingappan
The Startup

Recommended from Medium


See more recommendations