27 October, 2017KumuluzEEOpenAPIZvone Gazvoda

KumuluzEE OpenAPI in action

KumuluzEE OpenAPI was recently updated! with separate dependency for the OpenAPI UI. Check KumuluzEE OpenAPI - Updated

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.


You can enable KumuluzEE OpenAPI support by adding the following 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")))
public class JavaSiApplication extends Application {...}

Documenting resource class and operations

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")
    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:




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