Skip to content
KumuluzEE OpenAPI MicroProfile project provides powerful tools to incorporate the OpenAPI 3 specification to your microservices in a standardized way.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
core
.gitignore
.travis.yml
CONTRIBUTING.md
LICENSE
README.md
gpg.tar.gz.enc
pom.xml
settings.xml

README.md

KumuluzEE OpenAPI MicroProfile

Build Status

KumuluzEE OpenAPI MicroProfile project provides powerful tools to incorporate the OpenAPI 3 specification to your microservices in a standardized way.

KumuluzEE OpenAPI MicroProfile project allows you to document microservice APIs using OpenAPI v3 compliant annotations. Project will automatically hook-up servlet that will serve your API specifications on endpoint /openapi. The project implements the MicroProfile OpenAPI specification.

More details:

Usage

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

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

OpenAPI configuration

When kumuluzee-openapi-mp dependency is included in the project, you can start documenting your REST API using MicroProfile OpenAPI annotations.

Documenting application class

@SecurityScheme(securitySchemeName = "openid-connect", type = SecuritySchemeType.OPENIDCONNECT,
        openIdConnectUrl = "http://auth-server-url/.well-known/openid-configuration")
@ApplicationPath("v2")
@OpenAPIDefinition(info = @Info(title = "CustomerApi", version = "v2.0.0", contact = @Contact(), license = @License(name="something")), servers = @Server(url = "http://localhost:8080/v2"), security
        = @SecurityRequirement(name = "openid-connect"))
public class CustomerApplication extends Application {
}

Documenting resource class and operations

@Path("customers")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public class CustomerResource {

    @GET
    @Operation(summary = "Get customers details", description = "Returns customer details.")
    @APIResponses({
            @APIResponse(description = "Customer details", responseCode = "200", content = @Content(schema = @Schema(implementation =
                    Customer.class)))
    })
    @Path("{customerId}")
    public Response getCustomer(@PathParam("customerId") String customerId) {
        // ...
    }

}

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->/openapi

Example:

http://localhost:8080/openapi

Serving OpenAPI specification can be disabled by setting property kumuluzee.openapi-mp.enabled to false. By default serving API spec is enabled.

Configuration

The KumuluzEE OpenAPI MicroProfile extension can be configured with the standard KumuluzEE configuration mechanism. For example with the config.yml file:

kumuluzee:
  openapi-mp:
    enabled: true
    servlet:
      mapping: /openapi-custom-mapping
    scan:
      packages: com.kumuluz.ee.samples.openapi
    servers: https://example-api.com/v1,https://my-proxy.com/v1

Some interesting configuration properties are:

  • kumuluzee.openapi-mp.enabled - If set to false disables the extension (and OpenAPI servlet). Default value: true
  • kumuluzee.openapi-mp.servlet.mapping - The endpoint at which the OpenAPI specification is available. Default value: /openapi
  • kumuluzee.openapi-mp.scan.packages - Comma separated list of packages which are scanned for the OpenAPI annotations. By default, all packages are scanned.

Full list of configuration properties can be found in MicroProfile OpenAPI specification.

Changelog

Recent changes can be viewed on Github on the Releases Page

Contribute

See the contributing docs

When submitting an issue, please follow the guidelines.

When submitting a bugfix, write a test that exposes the bug and fails before applying your fix. Submit the test alongside the fix.

When submitting a new feature, add tests that cover the feature.

License

MIT

You can’t perform that action at this time.