Micronaut server generation using OpenApi specification

Table of contents

Reading Time: 3 minutes

In this article, we will create an OpenAPI specification file and use it to generate a Java Micronaut server API using the OpenAPI generator.

Installing OpenAPI generator

We can use the OpenAPI generator using multiple supported workflow integrations like Gradle, Maven, and SBT. Here, we are using the jar option, Download the binary, then place it in the project folder you want to use. To verify that generator works correctly run the help command, It should provide a description and a list of commands.

java -jar openapi-generator-cli.jar help

Creating Spec file

Let’s write a definition file outlining our server API’s available paths and operations. The file will be written in OpenAPI standard format having a specific structure. OpenAPI generator supports .yaml and .json file formats. We will create an employee-definition.yaml file.

General server info

openapi: 3.0.0

info:

  description: Employee API

  version: 1.0.0

  title: employee

  license:

    name: Apache-2.0

    url: "https://foo.bar"

  tags:

    - name: employee

      description: Search for employee and add new employee

openapi key tells the version that will be used for parsing. The info object describes general information about API like description, title, license etc. tags are used to logically structure different paths

Paths and operations

paths:

    /search:

      get:

        tags:

          - employee

        summary: Search for the employee

        operationId: search

        parameters:

          - name: department-name

            in: query

            schema:

              type: string
              
              minLength: 3

        responses:

          "200":

            description: Success

            content:

              "application/json":

                schema:

                  type: array,

                  items:

                    $ref: "#/model/EmployeeInfo"
          "400":

            description: Bad request

We define the GET operation on the /search path. We use the tag we previously defined for the employee. Note that a controller will be developed for each tag to carry out its actions. The search operationId will be used as the method name for the given path. We define parameters of the type string with length validation minLength that the user should supply in the query.

The responses object describes the response codes that can be produced by the API. In our case, API is producing 200 and 400 responses. Each response may contain more information regarding the response returned like description and return type. The schema for the employee info object will be defined later in components section of the definition.

Schemas

Schemas are equivalent to the POJO in an application. In our case, it is the employeeInfo object.

components:

    schemas:

      EmployeeInfo:

        title: Employee details

        description: Object containing details of Employee

        type: object

        properties:

          name: {type: string}

          empCode: {type: string}

          permanent: {type: boolean}

          contractor: {type: boolean}

We define the EmployeeInfo schema inside the components/schema section. From this schema Java classes will be generated with the same name. We will define the properties this class will hold along with their data type and validation if any.

Generating server API from the spec

Open the terminal in the same directory as employee-definition.yaml file and run the following command:

java -jar openapi-generator-cli.jar generate \

     -g java-micronaut-server \

     -i employee-definition.yaml \

     -o ./employee-api \

     -p controllerPackage=com.knoldus.micronaut.controller \

     -p modelPackage=com.knoldus.micronaut.model \

     -p build=maven \

     -p test=junit

-g specifies that we will use the Micronaut server generator.
-i specifies that the spec file that needs to be parsed.
-o specifies the output directory where the generated API will be created.
-p specifies parameters that help in generating the code as per the requirement. controllerpacke defines where all controllers will be created and similarly modelPackage defines where all the model classes will be placed. Then, we specified that we want to use the maven build and junit test suite.

Once the command is successfully executed, you may see following directory structure inside employee-api directory.

Conclusion

We’ve successfully generated Micronaut server API using the OpenAPI spec using the OpenAPI generator jar. We can now change the API code and update the spec.