Writing REST API with OpenAPI and SpringBoot

In this post we will see how to create a REST API with Spring boot.We will take a schema first approach and we will generate the REST API stub using the schema. This article will show how a OpenAPI specification looks like and how can we generate our REST API stub using the schema.

OpenAPI Specification

APIs are contract between the application and consumers of the application. These consumers can be machines or humans. OpenAPI is a specification to write your API contract in human and machine readable format. It standardizes the way we can describe our API. The entire specififaction can be found here https://spec.openapis.org/oas/v3.1.0 .

Our First API Spec

Let’s create a new service, I call it inventory-service. We now know how to generate a new spring boot application. We add a yml openAPI spec file in src/resources/spec/inventory-api.yml. A minimal API can look as follows -

It is a very minimal API . We can see in paths section we have description of our API. Each API endpoint has it’s optional request body and response body. We can also define if some custom headers are required, path parameters , query parameters and so on.

In the components section we define our models and these are referenced in our API.

I will not go deeper into the OpenAPI spec but because it is very vast but we can always consult the spec for our specific use case .

Generating REST API for Spring

Now that we have our OpenAPI spec, there are plugins and tool available to generate code from our spec. We can use the openapi-generator https://openapi-generator.tech/docs/installation to generate our REST API. We can use cli to generate our REST API.

However there is also a maven plugin https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin which we will use to generate our source .

The maven plugin uses the openapi-generator to generate the source code.

To use the maven-plugin we will add it to the build section like following -

Both the plugin and the actual openapi-generator has lot of config options we can check it from https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin and https://openapi-generator.tech/docs/generators/spring.

In the above example I have used the bare minimum config . I will explain them below .

• inputSpec — This is the path to the OpenAPI spec file.
• generatorName — ooenapi-generator can produce source code multiple language and framework. Because we want to generate for Spring I chose spring as the generator name.
• generateSupportingFiles — When I generated first I saw some unecessary supporting files were generated as I do not need those I turned it to false.
• configOptions — Properties that maps directly to the generator options.

Below are some config options —

• basePackage — package name for your generated sources
• sourceFolder — folder where your generated sources will be placed
• interfaceOnly — We can either generate only REST API interface or we can generate some default code. I make it true as I want to generate only REST API interface.
• modelPackage — package name for your generated model/dto classes.
• apiPackage — package name for your generated API classes.
• skipDefaultInterface — We can skip the genration of default methods in the interface.
• openApiNullable — With the value true it will generate an import of org.openapitools.jackson.nullable.JsonNullable however I didn’t need it so I make it false.

So what is the output of the above code ? Below is how our REST API stub looks like

Now we have our API interface , we can now create our controller and implement the methods.

So that’s it for this post, I will actually implement the API using tests so watch out for the next post.

This post is part of my series on Spring Boot . You can also follow the series on dev.to https://dev.to/sabyasachi/series/17765 . Follow me on https://twitter.com/sabz2301 .