Contract First OpenAPI Generation

Question

I tried to use a simple OpenAPI V3 API for implementing on OpenLiberty with a contract-first paradigm.

I use the following plugin for OpenAPI Code generation:

<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>3.2.2-SNAPSHOT</version>

For generation I use <generatorName>jaxrs-spec</generatorName>

As <configOptions> I use <useSwaggerAnnotations>false</useSwaggerAnnotations>

Beside the model classes the following Interface is generated:

@Path("/inventory")
public interface InventoryApi {

  @GET
  @Path("/systems/{hostname}")
  @Produces({ "text/plain", "application/json" })
  Response getPropertiesForHost(@PathParam("hostname") String hostname);

  @GET
  @Path("/systems")
  @Produces({ "application/json" })
  Response listContents();
}

I try to use my Implementation as lean as possible like this:

@RequestScoped
@Path("/")
public class InventoryImpl implements InventoryApi {

   public Response getPropertiesForHost(String hostname) {
      ...
   }

   public Response listContents() {
      ...
   }    
}

I can call with the following curl command curl -X GET "http://localhost:9080/properties-sample/systems" This works!

But I would have expected to use the following curl -X GET "http://localhost:9080/properties-sample/inventory/systems" But this does not work. I have to change the @Path in the Impl to @Path("/inventory"), so it works using curl -X GET "http://localhost:9080/properties-sample/inventory/systems"

Is this working as designed or are @Path Annotations on the interface irrelevant?

Does somebody else has another way of using contract first paradigm with OpenLiberty?

score 2 · Accepted Answer · answered Aug 21 '18 at 15:38

You're correct to use the OpenAPI Tools plugin for this. Open Liberty supports MicroProfile OpenAPI, which allows you to expose your contract-first OAS3 doc, but for generation purposes Open Liberty defers to the OSS OpenAPI Tools community.

This link should help guide your interface vs implementing class decisions with regards to the JAX-RS annotations. In particular, in your example you are overriding the main @Path annotation, hence the different behaviour.

Contract First OpenAPI Generation

1 Answers1