https://github.com/kumuluz/kumuluzee-openapi
KumuluzEE OpenAPI extension provides powerful tools to incorporate and visualize the OpenAPI 3 specification to your microservice.
https://github.com/kumuluz/kumuluzee-openapi
cloud-native java javaee kumuluzee microservices open-api-v3 openapi-spec openapi3 rest
Last synced: 4 months ago
JSON representation
KumuluzEE OpenAPI extension provides powerful tools to incorporate and visualize the OpenAPI 3 specification to your microservice.
- Host: GitHub
- URL: https://github.com/kumuluz/kumuluzee-openapi
- Owner: kumuluz
- License: other
- Created: 2017-10-27T06:46:32.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2025-07-12T01:58:08.000Z (11 months ago)
- Last Synced: 2026-01-17T17:42:03.429Z (5 months ago)
- Topics: cloud-native, java, javaee, kumuluzee, microservices, open-api-v3, openapi-spec, openapi3, rest
- Language: Java
- Homepage: https://ee.kumuluz.com
- Size: 632 KB
- Stars: 2
- Watchers: 14
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# KumuluzEE OpenAPI
[](https://travis-ci.org/kumuluz/kumuluzee-openapi)
> KumuluzEE OpenAPI project provides powerful tools to incorporate and visualize the OpenAPI 3 specification to your microservice.
KumuluzEE OpenAPI 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 ```/api-specs//openapi.[json|yaml]```. Furthermore, project allows you to integrate Swagger-UI into your
microservice that will visualize APIs documentation and allow you to interact with your API resources.
More details: [OpenAPI v3 Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md).
## Usage
You can enable KumuluzEE OpenAPI support by adding the following dependency:
```xml
com.kumuluz.ee.openapi
kumuluzee-openapi
${kumuluzee-openapi.version}
```
## OpenAPI configuration
When kumuluzee-openapi dependency is included in the project, you can start documenting your REST API using [Swagger-Core Annotations](https://github.com/swagger-api/swagger-core/wiki/Annotations-2.X).
### Documenting application class
```java
@SecurityScheme(name = "openid-connect", type = SecuritySchemeType.OPENIDCONNECT,
openIdConnectUrl = "http://auth-server-url/.well-known/openid-configuration")
@OpenAPIDefinition(info = @Info(title = "Rest API", version = "v1", contact = @Contact(), license = @License(), 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
```java
@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(
array = @ArraySchema(schema = @Schema(implementation = Session.class))),
headers = {@Header(name = "X-Total-Count", schema = @Schema(type = "integer"))}
)})
@SecurityRequirement(name = "openid-connect")
@GET
public Response getSessions() {...}
...
}
```
## Accessing API specification
Build and run project using:
```bash
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
`/api-specs` mapping can be renamed by setting the configuration property `kumuluzee.openapi.servlet.mapping`, For
example to move the above example to url http://localhost:8080/openapi-specs/v1/openapi.json use the following
configuration:
```yml
kumuluzee:
openapi:
servlet:
mapping: openapi-specs
```
Serving OpenAPI specification can be disabled by setting property **kumuluzee.openapi.spec.enabled** to false. By default serving API spec is enabled.
## Adding OpenAPI UI
To serve API specification in visual form and to allow API consumers to interact with API resources you can add OpenAPI UI by including dependency:
```xml
com.kumuluz.ee.openapi
kumuluzee-openapi-ui
${kumuluzee-openapi.version}
```
Dependency will include OpenAPI UI artifacts, in case you want to temporarily disable OpenAPI UI you can do so by setting configuration property:
```yaml
kumuluzee:
openapi:
ui:
enabled: false
```
After startup OpenAPI UI is available at: http://localhost:8080/api-specs/ui.
If you want to disable OpenAPI Dependency you can set the following property:
```yaml
kumuluzee:
openapi:
enabled: false
```
## Changelog
Recent changes can be viewed on Github on the [Releases Page](https://github.com/kumuluz/kumuluzee-openapi/releases)
## Contribute
See the [contributing docs](https://github.com/kumuluz/kumuluzee-openapi/blob/master/CONTRIBUTING.md)
When submitting an issue, please follow the
[guidelines](https://github.com/kumuluz/kumuluzee-openapi/blob/master/CONTRIBUTING.md#bugs).
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