October 27, 2017 Product Developers Zvone Gazvoda
KumuluzEE OpenAPI Swagger-UI

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.

Subscribe to our mailing list

Subscribe to our mailing list to get the latest news and updates.