API-First Design with OpenAPI Generator

APIs are contracts between services and their clients. These contracts are usually documented using an interface description language (IDL). Nowadays, the most popular IDL for RESTful interfaces is the OpenAPI Specification.

Unfortunately, even in small projects, it often happens that some of the interfaces don’t match what’s actually implemented. To solve this problem, we can adopt an “API-First Design” approach.

“An API-first approach involves developing APIs that are consistent and reusable, which can be accomplished by using an API description language to establish a contract for how the API is supposed to behave. Establishing a contract involves spending more time thinking about the design of an API. It also often involves additional planning and collaboration with the stakeholders providing feedback on the design of an API before any code is written.” — Swagger

This approach can be summarized in three simple steps:

• First step: Define and design the API interface.
• Second step: Review the definition with clients and API stakeholders.
• Third step: Implement the service.

In this article, we’ll look at how OpenAPI Generator can help us enforce this approach when building Spring Boot applications.

Setting Up the Project

The OpenAPI Generator Plugin

A Maven plugin supports the OpenAPI generator project.

Add the following plugin in the pom.xml file:

<plugin> <groupId>org.openapitools</groupId> <artifactId>openapi-generator-maven-plugin</artifactId> <!-- RELEASE_VERSION --> <version>${openapi-generator-maven-plugin.version}</version> <!-- /RELEASE_VERSION --> <executions> <execution> <goals> <goal>generate</goal> </goals> <configuration> <!-- specify the openapi description file --> <inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec> <!-- target to generate java server code --> <generatorName>spring</generatorName> <!-- pass any necessary config options --> <configOptions> <documentationProvider>springdoc</documentationProvider> <modelPackage>org.company.model</modelPackage> <apiPackage>org.company.api</apiPackage> <openApiNullable>false</openApiNullable> </configOptions> </configuration> </execution> </executions> </plugin> 

You need to configure the inputSpec tag value with the full path to your OpenAPI description file.

All the plugin configuration parameters are contained in the configOptions tag. Make sure you set the modelPackage and apiPackage tags with the package names in your project.

Dependencies

Models and APIs are generated using SpringDoc, as well as Bean Validation 2.0 (JSR 380).

In your pom.xml file, include the following dependencies:

<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>${springdoc.version}</version> </dependency> <!-- Bean Validation API support --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-validation</artifactId> </dependency> <dependency> <groupId>javax.validation</groupId> <artifactId>validation-api</artifactId> </dependency> 

First Step: Define and Design

Our plan is to create two endpoints for the Orders Service API:

• POST /orders — creates an order.
• GET /orders/:id — returns the order information.

We use OpenAPI Specification 3.0.3 in this tutorial. At the time I’m writing this article, most Specification 3.0 features are supported by OpenAPI Generator. However, Specification 3.1 will be supported shortly.

Below is an example of an openapi.yml file that you can use as a reference for creating your OpenAPI files.

openapi: 3.0.3	info: title: Order Service API version: 1.0.0	paths: /orders: post: summary: creates an order operationId: createOrder requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OrderRequest' responses: 201: description: Order created. 400: description: Malformed syntax of the request params. content: application/problem+json: schema: $ref: '#/components/schemas/ErrorDetails' /orders/{id}: get: summary: Returns the order information operationId: getOrder parameters: - in: path name: id allowEmptyValue: false description: Order guid. required: true schema: type: string pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$' example: 'e06bf865-312c-4e2a-85c3-cc20db4a4c1d' responses: 200: description: Order details. content: application/json: schema: $ref: '#/components/schemas/OrderResponse' 400: description: Malformed syntax of the request params. content: application/problem+json: schema: $ref: '#/components/schemas/ErrorDetails' 404: description: The requested resource doesn't exists or was removed.	components: schemas: OrderRequest: description: Order placed from a consumer. type: object properties: notes: description: Notes from consumer. type: string maxLength: 1000 example: add mayonnaise orderItems: type: array items: $ref: '#/components/schemas/OrderItemRequest' consumer: $ref: '#/components/schemas/ConsumerRequest' OrderItemRequest: description: Item in the order. type: object properties: name: description: Item name. type: string minLength: 3 maxLength: 32 example: Royale with Cheese quantity: description: Item quantity. type: integer minimum: 1 maximum: 100 example: 2 ConsumerRequest: description: Consumer information. type: object properties: name: description: Consumer name. type: string minLength: 5 maxLength: 64 example: Vincent Vega address: description: Consumer address. type: string minLength: 5 maxLength: 64 example: 1234 Big Kahuna St, Los Angeles CA phone: description: Consumer phone number. type: string minLength: 10 maxLength: 12 pattern: ^[+]?[0-9]*$ example: +1223334444 OrderResponse: description: Order placed from a consumer. type: object properties: id: description: Order guid. type: string example: 'e06bf865-312c-4e2a-85c3-cc20db4a4c1d' state: description: Order state. type: string enum: [ 'APPROVAL_PENDING','APPROVED','REJECTED','CANCEL_PENDING','CANCELLED','REVISION_PENDING' ] example: 'APPROVAL_PENDING' notes: description: Notes from consumer. type: string example: add mayonnaise orderItems: type: array items: $ref: '#/components/schemas/OrderItemResponse' consumer: $ref: '#/components/schemas/ConsumerResponse' OrderItemResponse: description: Item in the Order. type: object properties: name: description: Item name. type: string example: Royale with Cheese quantity: description: Item quantity. type: integer example: 2 ConsumerResponse: description: Consumer information. type: object properties: name: description: Consumer name. type: string example: Vincent Vega address: description: Consumer address. type: string example: 123 Big Kahuna St, Los Angeles CA phone: description: Consumer phone number. type: string example: +1223334444 ErrorDetails: type: object properties: code: description: Application error code. type: integer nullable: false example: 400 detail: description: A short, summary of the problem type. type: string nullable: false example: 'size must be between 10 and 12.' field: description: The field that caused the error. type: string example: 'consumer.phone' value: description: The value of the field that caused the error. type: object example: null location: description: The location of the field that caused the error. type: string enum: [ 'BODY','PATH','QUERY','HEADER' ] example: 'BODY' 

Second Step: Review with Stakeholders

Stakeholders need to validate the API definition once it has been created. To generate the API stub, compile the application with the command below.

$ mvn clean compile 

Next, run the application.

$ mvn spring-boot:run 

You can access the Swagger UI by opening the following URL in your browser: http://localhost:8080/swagger-ui/index.html.

Third Step: Implement

As a next step, let’s implement the service in accordance with the definition.

OrderController

package org.company.rs; import org.company.model.*; import org.company.api.OrdersApi; @RestController public class OrderController implements OrdersApi { private final OrderService service; private final OrderControllerMapper mapper; public OrderController(OrderService service, OrderControllerMapper mapper) { this.service = service; this.mapper = mapper; } @Override public ResponseEntity<Void> createOrder(OrderRequest orderRequest) { final UUID id = service.createOrder( mapper.orderRequestToOrder(orderRequest) ); URI location = ServletUriComponentsBuilder.fromCurrentRequest() .path("/{id}").buildAndExpand(id) .toUri(); return ResponseEntity.created(location).build(); } @Override public ResponseEntity<OrderResponse> getOrder(String id) { Order order = service.getOrder( UUID.fromString(id) ); return ResponseEntity.ok( mapper.orderToOrderResponse(order) ); } } 

Here, we have created the OrdersController class that implements the generated org.company.api.OrdersApi interface.

Additionally, we have imported org.company.model.*, which includes all generated request and response objects.

ExceptionController

As mentioned earlier, OpenAPI Generator supports Bean Validation. Hence, we can handle exceptions thrown by these validations and send descriptive error responses to clients.

package org.company.rs; import org.company.rs.model.ErrorDetails; @ControllerAdvice public class ExceptionController { @ExceptionHandler(BindException.class) ResponseEntity<List<ErrorDetails>> handleBindException(BindException ex) { List<ErrorDetails> errors = ex.getBindingResult().getFieldErrors().stream() .map(fieldError -> { ErrorDetails errorDetails = new ErrorDetails(); errorDetails.setCode(400); errorDetails.setDetail(fieldError.getDefaultMessage()); errorDetails.setField(fieldError.getField()); errorDetails.setValue(fieldError.getRejectedValue()); errorDetails.setLocation(ErrorDetails.LocationEnum.BODY); return errorDetails; }).toList(); return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(errors); } @ExceptionHandler(ConstraintViolationException.class) ResponseEntity<List<ErrorDetails>> handleConstraintViolationException(ConstraintViolationException ex) { List<ErrorDetails> errors = ex.getConstraintViolations().stream() .map(constraintViolation -> { ErrorDetails errorDetails = new ErrorDetails(); errorDetails.setCode(400); errorDetails.setDetail(constraintViolation.getMessage()); errorDetails.setField(constraintViolation.getPropertyPath().toString()); errorDetails.setValue(constraintViolation.getInvalidValue()); errorDetails.setLocation(ErrorDetails.LocationEnum.PATH); return errorDetails; }).toList(); return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(errors); } } 

@ControllerAdvice is an annotation that allows us to handle exceptions in one place across the entire application.

To handle errors on the client side, a handler method annotated with @ExceptionHandler is defined for BindException.class and ConstraintValidationException.class.

Thanks for reading. I hope this was helpful!

The example code is available on GitHub.