API first approach has a ton of advantage's, it helps developers and functional analysts to visualize the APIs before developers start implementing it. It also helps the UI developers and the testers to start working on their tasks parallelly while developers are busy implementing.
In this blog I will explain how to create such API contracts with Swagger 3.0 on OpenAPI specifications (OAS) and using Maven, how can we easily generate Spring Boot code for such contracts.
Swagger/OpenAPI contract
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.
An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.
- Source : https://swagger.io/specification/
OpenAPI specs has a few major sections while defining the APIs:
- Info
- Tags
- Paths
- Components
Info: Holds API title, description, version, contact and license information.
Tags: Holds different tags for the API definitions, a useful way to segregate APIs, this is quite useful if you are using Swagger editor to navigate the APIs. You are can also use tags to document your APIs better.
Paths: As the name suggests, it holds all your API paths. It defines, the REST operation, description, request, response structures and HTTP response codes.
Components: This is to define the objects (models) you use in your API definitions also the reusable HTTP response codes.
You can choose to write the specs in JSON or YAML. A basic example looks like below.
 |
| -source "swagger.io/docs/specification/basic-structure/" |
While generating code using Maven plugin, paths and components are being leveraged to generate code.
The example is based on my previous blog on Liquibase+Spring boot
Example API spec : API Spec for Providers/Services (I have excluded Citizen APIs for the time being)
As you can see above, I have defined 7 endpoints, with some standard info and a couple of tags.
Lets dive into one of the paths:
This is a get all services endpoint, which returns an array of “Service” objects (this is defined in components, that’s why a $ref). It also defines that it is being tagged as Service API and other HTTP error codes with a return message.
Above, the “operationId” will be later used to generate the controller method name.
How does a component looks like:
Here you define the basic object structure with some example values and also if this object also refers to another object within the components (such as Provider).
More info, on how to define such contracts using OAS can be found here.
Code generation
Code generation can be for server (the API implementation itself) or client (connecting the API). Although, for client you can still choose use Feign clients for more diverse and sophisticated implementation depending on your requirements.
I will concentrate on the server side of it, since that’s reduces a lot of boilerplate code for you.
The easiest way to do this, is to use https://editor.swagger.io/ and do this from the browser, if you choose to. But this won’t help you to make generation and maintenance easier.
Maven plugin
OpenAPI provides an useful maven plugin which you can use to generate the code from these types of contracts.
Link to repo is here.
The documentation talks about all the properties you can configure to generate server or a client. I will show you my example on the server part.
A few major properties are, where to find the yaml file containing the specs, package names for your generated classes.
With the spec, I shared earlier, if we use the above plugin, the generated classes looks like this:
FYI: I faced a few compilation errors, due to unused imports in the generated classes, which you can avoid by using a different template.
More info on:
- https://github.com/OpenAPITools/openapi-generator/issues/8776
- https://github.com/OpenAPITools/openapi-generator/issues/2901
I had to add some extra dependencies to resolve this, you can also do that temporarily to avoid compilation issues.
Closer look at the generated classes
API-Controller-Delegate
OpenAPI plugin generates 2 interfaces and 1 class. One interface for API which gets implemented by Controller, they both combined defines the endpoints.
There will be as many number of API-Controller combination as the number of “paths” you have defined in the yaml.
Another interface, xxxDelegate which should be implemented by a @Service implementation of Spring Boot.
The delegate interface, comes from the plugin config properties, delegatePattern = true. You can choose to disable this, but I find it quite useful from the perspective of “separation-of-concerns” concept.
Model
The plugin also generates all the model objects defined in the components section of the API spec.
This is a simple POJO with all defined properties from the spec with annotations defining non-nulls, required etc. attributes.
Complete the implementation with Service & Repository
Now that we have the basic code generated for the endpoints, we just need to implement the repository and service classes (and possibly the entities). In this example, I have also created the entities, since I like to keep the response-request objects separated from the DB structure.
BTW, the convertion between entity-to-response object has been done using Mapstruct.
The complete implementation is in Github.
Running the application
If you just run the SerivceRepositoryApplication class, all the APIs will be available and you can invoke them using your favorite client.
Comments
Post a Comment