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.
OpenAPIOn 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.
Press enter or click to view image in full size Swagger EditorAn OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
OpenAPI SpecificationIt 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:
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.
Press enter or click to view image in full size Screenshot of Project Structure OpenAPI GeneratorTo generate automatically DTOs objects and the Rest Interface, we can use the plugin openapi-generator-maven-plugin (to Gradle, use this plugin — thanks
). 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…
ImplementationThe 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)
Press enter or click to view image in full size Automatically generated interfaceThis 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 ClientsUsing 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.
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!
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4