KumuluzEE OpenAPI in action

KumuluzEE OpenAPI extension allows you to document microservice APIs using OpenAPI v3 compliant annotations. Extension will automatically hook-up servlet that will serve your API specifications on endpoint /api-specs/<jax-rs application-base-path>/openapi.[json|yaml]. Furthermore, extensions allows you to integrate Swagger-UI into your microservice that will visualize APIs documentation and allow you to interact with your APIs resources.

More details: OpenAPI v3 Specification.

Usage

You can enable KumuluzEE OpenAPI support by adding the following dependency:

<dependency>
    <groupId>com.kumuluz.ee.openapi</groupId>
    <artifactId>kumuluzee-openapi</artifactId>
    <version>${kumuluzee-openapi.version}</version>
</dependency>

OpenAPI configuration

When kumuluzee-openapi dependency is included in the project, you can start documenting your REST API using Swagger-Core Annotations.

Documenting application class

@SecurityScheme(name = "openid-connect", type = SecuritySchemeType.OPENIDCONNECT, 
                openIdConnectUrl = "http://auth-server-url/.well-known/openid-configuration")
@OpenAPIDefinition(info = @Info(title = "Rest API", version = "v1", description = "JavaSI API for managing conference.", 
                    security = @SecurityRequirement(name = "openid-connect"), servers = @Server(url ="http://localhost:8080/v1")))
@ApplicationPath("v1")
public class JavaSiApplication extends Application {...}

Documenting resource class and operations

@Path("sessions")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public class SessionsResource {

    @Operation(description = "Returns list of sessions.", summary = "Sessions list", tags = "sessions", responses = {
            @ApiResponse(responseCode = "200",
                    description = "List of sessions",
                    content = @Content(
                            schema = @Schema(implementation
                            = Session.class)),
                    headers = {@Header(name = "X-Total-Count",
                            schema = @Schema(type = "int"))}
                    )})
    @SecurityRequirement(name = "openid-connect")
    @GET
    public Response getSessions() {...} 
    ...
}

Accessing API specification

Build and run project using:

mvn clean package
java -jar target/${project.build.finalName}.jar

After startup API specification will be available at:

http://<-hostname-:<-port->/api-specs/<-application-base-path->/openapi.[json,yaml]

Example:

http://localhost:8080/api-specs/v1/openapi.json

Visualize OpenAPI documentation with OpenAPI UI

In order to include OpenAPI UI (based on SwaggerUI) to your project, you have to include maven dependency:

<dependency>
    <groupId>com.kumuluz.ee.openapi</groupId>
    <artifactId>kumuluzee-openapi-ui</artifactId>
    <version>${kumuluzee-openapi.version}</version>
</dependency>

Dependency automatically adds OpenAPI UI to the project. OpenAPI UI is available at http://localhost:8080/api-specs/ui.

In case you want to temporarily disable OpenAPI UI you can do so by setting configuration property:

kumuluzee:
  openapi:
    ui:
      enabled: false

Read more about extension at KumuluzEE OpenAPI and explore sample project at KumuluzEE OpenAPI Sample.

Blog