OpenAPI

An OpenAPI description of the API is always generated for all the controllers.

The annotation processor that generates the web route adapters also generates a OpenAPI (swagger) definition of all the endpoints that the controllers define.

Example javalin-maven-java-basic

Javadoc / Kotlin doc

The annotation processor reads the javadoc (and Kotlin documentation) for the controller methods and the description, @param and @return documentation is all used in the OpenAPI definition. The processor reads all the request and response types as OpenAPI component schema.

Validation annotations - @NotNull, @Size, @Email etc

The javax bean validation annotations @NotNull, @Size and @Email are read as well as detecting Kotlin non-nullable types as required properties.

These are used to specify required properties, min max lengths and property format.

Swagger annotations

We can add a dependency on io.swagger.core.v3:swagger-annotations:2.0.8 and add swagger annotations.

@OpenAPIDefinition

We use @OpenAPIDefinition to define a title and description for the api. This annotation would often go on the Main method class or on package-info.java in the controllers package.

Example @OpenAPIDefinition

@OpenAPIDefinition(
  info = @Info(
    title = "Example service",
    description = "Example Javalin controllers with Java and Maven"))

@Hidden

Put @Hidden on controller methods that we want to exclude from the OpenAPI documentation.

Gradle plugin

The gradle plugin by default puts the generated openapi.json file into src/main/resource/public

To add the plugin:

plugins {
  ...
  id('io.dinject.openapi') version('1.2')
}

To configure the openapi.json file to go to another location add a openapi configuration section in build.gradle like:

openapi {
  destination = 'other/my-api.json'
}

Maven plugin

The maven plugin by default puts the generated openapi.json file into src/main/resource/public

To add the plugin into build / plugins section:

<plugin>
  <groupId>io.dinject</groupId>
  <artifactId>openapi-maven-plugin</artifactId>
  <version>1.2</version>
  <executions>
    <execution>
      <id>main</id>
      <phase>process-classes</phase>
      <goals>
        <goal>openapi</goal>
      </goals>
    </execution>
  </executions>
</plugin>

To configure the openapi.json file to go to another location add a configuration section element like:

<plugin>
  <groupId>io.dinject</groupId>
  <artifactId>openapi-maven-plugin</artifactId>
  <version>1.2</version>
  <configuration>
    <destination>other/my-api.json</destination>
  </configuration>
  <executions>
    <execution>
      <id>main</id>
      <phase>process-classes</phase>
      <goals>
        <goal>openapi</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Serving openapi.json

When the openapi.json file is in src/main/resources/public it can be served by using addStaticFiles on the JavalinConfig like:

Javalin app = Javalin.create(config -> {
  ...
  config.addStaticFiles("public", Location.CLASSPATH);
});