Microprofile OpenAPI: generate your openapi.json at build time with Geronimo and Maven!

Microprofile OpenAPI allows to serve an openapi.json to document your API. However, by default it does it by introspecting at runtime your application. The time is not that an issue today...but it means you need a runtime....for a doc. Yes, this is one of the pitfall of the Swagger/OpenAPI programmatic approach: you must serve the documentation of your API from your application.

In most cases you will want to provide the documentation somewhere else - like a static website - and just enable (or disable) the client/test mode to another demo service to keep the overall documentation sane and consistent.

This leads to extracting the in memory openapi.json and including it in your doc. Not very complicated but it requires some step to do on your side like a test which starts a server, captures the JSON and saves it in a good place or something equivalent.

To avoid that headache and match this common case, Geronimo Microprofile OpenAPI implementation provides a Maven plugin to just generate the file at build time.

To get started just declare the plugin like that in your pom:

<plugin>
  <groupId>org.apache.geronimo</groupId>
  <artifactId>geronimo-openapi-maven-plugin</artifactId>
  <version>${openapi.version}</version>
  <executions>
    <execution>
      <id>generate-openapi.json</id>
      <goals>
        <goal>openapi.json</goal>
      </goals>
      <configuration>
        <application>com.test.MyApp</application>
        <endpointClasses>
          <endpointClass>com.test.SomeEndpoint</endpointClass>
          <endpointClass>com.test.SomeOtherEndpoint</endpointClass>
        </endpointClasses>
      </configuration>
    </execution>
  </executions>
</plugin>

You need to list the JAX-RS application class (if any) and the JAX-RS endpoints to introspect in the generation and automatically a META-INF/openapi.json file. Indeed the plugin allows to change the output location to match a documentation need. This default value is coming from the specification one which allows to read an existing, already saved model.

Tip: if you want to avoid the server to scan for OpenAPI annotations, ensure to set in your microprofile configuration the boolean mp.openapi.scan.disable to true.