Enunciate vs. Microprofile OpenAPI: A Code First Approach

At tech11 – as mentioned in previous articles such as our "frontend technology stack" – we are fans of standards!

Microprofile OpenAPI is a standard that is implemented in almost all runtimes.

You may be wondering, why we use Enunciate and not OpenAPI in our source code. Here’s the answer.

What is Enunciate?

"Enunciate is a build-time Web service enhancement tool that can be applied to Java-based projects for generating a lot of cool artifacts from the source code of your Web service endpoints." – via GitHub.

Big thanks to Ryan Heaton , who is doing a great job via "stoicflame" on GitHub! ??

Why we chose Enunciate over OpenAPI?

To document our software, we use Enunciate (and therefore no additional swagger/openAPI annotations) to avoid repeating ourselves!

Don’t repeat yourself!

This means, that with enunciate we also generate openapi.yml / openapi.json – but only from "things" that already exist: like jax-rs annotations and javadocs.

To get our (REST) API documentation generated (as html pages):

As well as the “default“ Swagger UI, which we render based on our openapi.yml/openapi.json (generated by enunciate):

How do we generate documentation?

To get the documentation up and running, we code and document our code as usual. In doing so, we just use what we need. The "magic" is done by Enunciate, which extracts the necessary information directly from the code.

The following code uses jax-rs annotations and javadocs:

/*
?* Tasks resource to manage tasks ({@link TaskDTO}).
?*/
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public interface TasksResource {

?/**
?* Queries for tasks that fulfill a given filter.
?*
?* @param queryParams
?* query filter
?* @return list of tasks that fulfill the filter
?*/
?@GET
?TasksDTO queryTasks(@BeanParam QueryTasksParams queryParams);

?/**
?* Get the (distinct) collection of task types (names).
?*
?* @param queryParams
?* query filter
?* @return set of task types (names) that fulfill (parts of) the filter
?*/
?@GET
?@Path("types")
?TaskTypesDTO getTypes(@BeanParam QueryTasksParams queryParams);

?/**
?* Get the (distinct) collection of assignees (names) currently assigned to (filtered) tasks.
?*
?* @param queryParams
?* query filter
?* @return set of assignees (names) that fulfill (parts of) the filter
?*/
?@GET
?@Path("assignees")
?AssigneesDTO getAssignees(@BeanParam QueryTasksParams queryParams);



...

}*        

Learn more about Enunciate on GitHub, where we also share our knowledge.