OpenAPI Generation with Spring

1 Overview

In this article we consider example of using code generation by OpenAPI specification. This is the API-First approach to building service. Code generator will be used for generating code in java-spring application. Full source code of example project on GitHub

2 Specification

Let's start with writing simple OpenAPI specifications. Here we use an example with 'Get' and 'Create' operations for some Clients.

openapi: 3.0.3
info:
  title: client-api
  description: 'Client API'
  version: 1.0.0
paths:
  /client:
    get:
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: string
            format: uuid
            description: Client id
      responses:
        200:
          description: Success response with client
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientResponse"
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Client'
        required: true
      responses:
        200:
          description: Success response with client
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientResponse"
components:
  schemas:
    ClientResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Operation success flag
        message:
          type: string
          description: Error description
        client:
          $ref: "#/components/schemas/Client"
      required:
        - success
        - message
        - object
    Client:
      type: object
      description: Client data
      properties:
        id:
          type: string
          format: uuid
          description: Client unique id
        name:
          type: string
          description: Client name
          maximum: 32
          minimum: 2
        dateOfBirth:
          type: string
          format: date
        createdAt:
          type: string
          description: Date of client registration
          format: date-time
        banned:
          type: boolean
          description: Ban flag
        countAccounts:
          type: integer
          description: Count of client accounts
          minimum: 0
        serviceRate:
          type: string
          description: Service rate
          enum:
            - "FREE"
            - "STANDARD"
            - "VIP"

3 Setup dependencies

Let's setup OpenAPI generator maven plugin

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>6.2.0</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/specs/client-api.yaml</inputSpec>
                <generatorName>spring</generatorName>
                <apiPackage>dev.toliyansky.openapi.api</apiPackage>
                <modelPackage>dev.toliyansky.openapi.model</modelPackage>
            </configuration>
        </execution>
    </executions>
</plugin>

4 Code examples

After run mvn clean install generated classes will be placed into target directory.

To implement the HTTP route we should create a class that extends generated controller.

@RestController
@RequestMapping("/api")
public class ClientController extends ClientApiController {

    private final RandomExceptionService randomExceptionService;

    public ClientController(NativeWebRequest request, RandomExceptionService randomExceptionService) {
        super(request);
        this.randomExceptionService = randomExceptionService;
    }

    @Override
    public ResponseEntity<ClientResponse> clientGet(UUID id) {
        var clientResponse = new ClientResponse();
        try {
            var client = new Client(); // Stub. But in real project get client from service level.
            clientResponse.setSuccess(true);
            clientResponse.setClient(client);
            randomExceptionService.generateException50percentChance();
            return ResponseEntity.ok(clientResponse);
        } catch (Exception e) {
            e.printStackTrace();
            clientResponse.setSuccess(false);
            clientResponse.setMessage(e.getMessage());
            clientResponse.setClient(null);
            return ResponseEntity.internalServerError().body(clientResponse);
        }
    }

    @Override
    public ResponseEntity<ClientResponse> clientPost(Client client) {
        var clientResponse = new ClientResponse();
        try {
            // Do some actions with client in service level.
            client.id(UUID.randomUUID());
            clientResponse.setSuccess(true);
            clientResponse.setClient(client);
            randomExceptionService.generateException50percentChance();
            return ResponseEntity.ok(clientResponse);
        } catch (Exception e) {
            e.printStackTrace();
            clientResponse.setSuccess(false);
            clientResponse.setMessage(e.getMessage());
            clientResponse.setClient(null);
            return ResponseEntity.internalServerError().body(clientResponse);
        }
    }
}

Now we can test it with HTTP request

### Create client
POST http://localhost:8080/api/client
Content-Type: application/json
------
HTTP/1.1 200 
Content-Type: application/json
{
  "success": true,
  "message": null,
  "client": {
    "id": "6796a90a-314a-4667-a7cc-dfbe592b27e5",
    "name": "Anatoliy",
    "dateOfBirth": "2020-01-01",
    "createdAt": "2020-01-01T00:00:00Z",
    "banned": false,
    "countAccounts": 3,
    "serviceRate": "VIP"
  }
}

### Get client by id
GET http://localhost:8080/api/client?id=6796a90a-314a-4667-a7cc-dfbe592b27e5
Accept: application/json
------
HTTP/1.1 200 
Content-Type: application/json
{
  "success": true,
  "message": null,
  "client": {
    "id": "6796a90a-314a-4667-a7cc-dfbe592b27e5",
    "name": "Anatoliy",
    "dateOfBirth": "2020-01-01",
    "createdAt": "2020-01-01T00:00:00Z",
    "banned": false,
    "countAccounts": 3,
    "serviceRate": "VIP"
  }
}

5 Conclusion

In this article, we saw how to generate a java-spring service with an API-First approach with OpenAPI YAML specification and OpenAPI generator maven plugin.

Full source code of example project on GitHub