API-First with Spring WebFlux and OpenAPI Generator

In this story, we’ll explore how to generate codes using the swagger-codegen from the defined OpenAPI file in a spring reactive application.

· What we need
· Overview
∘ What is API-First?
∘ Why API-First?
· OpenAPI Specification
· Spring Webflux Application
· Test the API
∘ Import OpenAPI definition in insomnia
∘ Test
· Conclusion
· References

Teams and organizations continue to embrace an API-first philosophy. — 2022 State of the API Report

In recent years, APIs have become the building blocks of software for companies and organizations. These companies use them to offer new services for their internal or external partners.
Therefore, it is necessary to provide service contracts, with documentation that constitutes an agreement between the different stakeholders.

What we need

• Spring Boot 3
• Maven 3.8.+
• Java 17
• Postman or Insomnia

Overview

What is API-First?

API-first development is a development model in which applications are conceptualized and built by composing internal or external services delivered through APIs. This approach involves designing every API around a contract written in an API description language like OpenAPI.

Why API-First?

• Increasing developer productivity: Developers do not have to wait for updates to an API to be released before moving on to the next API. Teams can mock APIs and test API dependencies based on the established API definition.
• Reduces the risk of failure: API-First reduces the risk of failure by ensuring that APIs are reliable, consistent, and easy for developers to use.
• Reduces development cost: APIs specifications can be reused on many different projects. When a development team wants to build a new app, they don’t have to start from scratch which is time-consuming and costly. API-First design also allows most problems to be solved before any code is even written which helps prevent problems when it is time to integrate APIs with applications.
• Increases speed: API-First makes it possible to add new services and technologies to applications without having to re-architect the entire system. It allows businesses to optimize their speed to market by reusing existing software.
• Improve developer Experience: API-First ensures that developers have positive experiences using your APIs. Well-designed, well-documented, consistent APIs provide positive developer experiences because it’s easier to reuse code and onboard developers, and it reduces the learning curve.

OpenAPI Specification

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic.

The first thing to do is to define our API specification. In this story, we will create a library API, which will expose service contracts for CRUD operations.

An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format. For this story, we will use YAML format.

Our YAML specifications file:

The Swagger Editor offers an easy way to get started with the OpenAPI Specification (formerly known as Swagger) as well as the AsyncAPI specification, with support for Swagger 2.0, OpenAPI 3.0, and AsyncAPI 2.* versions.

The OpenAPI specification’s header contains some metadata about the API.

https://spec.openapis.org/oas/latest.html#openapi-object

Spring Webflux Application

Now that we have completed the OpenAPI specification, we can move on to using it in our project. Let’s start by creating a simple Spring Reactive project from start.spring.io, with the following dependencies: Spring Reactive Web and Lombok.

Add the OpenAPI specification to thesrc/main/resources/openapi/yaml directory with name library-openapi.yaml.

Then, we’ll be using the Open API Generator Maven plugin in the build section of the pom file.

In order to fix compilation issues, we need to add additional dependencies to the pom.xml file:

Run the command: mvn clean compile.The generator will generate the endpoint interfaces and DTO classes under the target folder.

For sample, the generated interface for the Book Controller API looks as follows:

We can implement the BookApi interfaces created in our project like this:

This implementation of the controller class is shortened to simply return static dummy data. We notice that our class BookController implements all the methods of the interface generated BookApi.

Test the API

Import OpenAPI definition in insomnia

Import data from a file > Select OpenAPI file > New > Request Collection

Test

Now we can run our application and test it.

POST /api/v1/book

GET /api/v1/book

Done. It works fine. 🙂

Conclusion

In this story, we learned how to use the OpenAPI specification in a spring Webflux project. At this point, the development team can start implementing the business logic.

The complete source code is available on GitHub.

References

• https://www.postman.com/state-of-api/
• https://spec.openapis.org/oas/latest.html
• https://openapi-generator.tech/docs/generators/spring/
• https://www.postman.com/api-first/
• https://swagger.io/resources/articles/adopting-an-api-first-approach/
• https://github.com/swagger-api/swagger-codegen/tree/master/modules/swagger-codegen-maven-plugin
• https://github.com/OpenAPITools/openapi-generator