API First, using OpenAPI and Spring Boot
Intro
Well, after some years of working with OpenAPI and Spring Boot, I’ve seen that some experienced developers don't know this approach.
On my last projects, I used the OpenAPI specification to generate DTO objects and interfaces for RestControllers on Spring Boot, and the front-end team went with the OpenAPI specification to create objects and clients for API.
This article will explain how OpenAPI and Spring Boot work together to use API First Concept.
OpenAPI
On the official website:
The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
The Open API Spec below contains POST, GET, PATCH, and DELETE requests/responses with Multipart and Path Params. So, it’s simple and easy to read, but Swagger Editor is simpler and is better to test/code.
An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
It might seem confusing at first, but given the declarative way of writing the spec in YAML it gets pretty straightforward and, most of all, very readable. Nevertheless, there are many tools for aiding in this process.
IMHO, the most important part is:
- Paths: Incremental (/v1/user before /v1/user/{id})
- Parameters (path, query, header, and cookies) and Request Body (JSON, multipart, etc)
- Components: The component’s definition with your properties, types, and formats. See the reference here.
Project Structure
In this example, the project structure is a parent pom with 2 modules: one for specification (openapi.yaml) and the other for implementation (of this specification), called impl.
OpenAPI Generator
To generate automatically DTOs objects and the Rest Interface, we can use the plugin openapi-generator-maven-plugin (to Gradle, use this plugin — thanks Aleksandar Stoisavljevic). An example of the POM using this plugin:
This definition will generate these classes:
On implementation, we add a dependency to this module.
<dependency>
<groupId>io.xgeeks.demo.api</groupId>
<artifactId>first-api-spec</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>In a perfect environment, this artefact will be pushed to an artefact manager like Nexus, JFrog, GitLab, Github…
Implementation
The signature of the REST methods is defined by the API spec itself. In my opinion, this is the best advantage to use OpenAPI to implement API First Approach from a back-end perspective using OpenAPI Generator. Let's see the UserApi interface (generated by OpenAPI Generator)
This is a way to keep the confidence of your spec between Front-end, Back-end, and thirty-party applications for example. Response, payload, parameters, mappings, everything is defined by OpenAPI. So, in my module implementation (first-api-impl), I just need to implement all the methods from the previously generated interface:
You can see and use my demo on my Github:
And the Front End?
In my previous project, front-enders used an auto generator plugin for React to generate clients and types automatically. On this website, it is possible to check a list with a lot of client generators for multiple technologies and programming languages.
An API First approach gives front-enders the benefit to use a MockServer and the OpenAPI spec. while the backend part isn’t fully implemented for testing, allowing a faster pace this way.
Auto-Generated Clients
Using a Swagger-Codegen plugin, it is possible to generate automatically clients in spec dependency. This will help communication between distributed systems using HTTP requests. In this article we will not cover this question, but here is the information.
Why using this approach and not others? (by Luis Nina)
In my opinion, this approach serves two main purposes: 1. helps back-enders define the proper methods to be implemented and for front-ends makes them advance in it’s own pace without the API fully implemented; 2. The other major purpose (not specific to this approach only but OpenAPI generally) is the fact that this kind of spec creates a contract between interested parties, teams can use a multitude of tools and technologies as long as they comply with the spec is all good.
Why using this approach and not others? (by Micael Vianna)
In addition to what Luis Nina commented, API First allows developers to think through the application better, negotiate with other teams before deploying, and not cause touchpoint waits.
References:
https://openapi-generator.tech/docs/generators/
https://editor.swagger.io/
https://swagger.io/docs/specification/about/
https://swagger.io/docs/specification/data-models/data-types/
https://github.com/mEstrazulas/demo-api-first
https://www.mock-server.com/mock_server/using_openapi.html
https://github.com/muonsoft/openapi-mock
https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin
https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen-maven-plugin/
https://www.baeldung.com/spring-boot-rest-client-swagger-codegen#1-maven-plugin
Special thanks to Luis Nina for suggestions and José Perdigão for corrections.
If you enjoy working on large-scale projects with global impact and if you like a real challenge, feel free to reach out to us at xgeeks! We are growing our team and you might be the next one to join this group of talented people 😉
Check out our social media channels if you want to get a sneak peek of life at xgeeks! See you soon!
