Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
265 lines (199 sloc) 10.4 KB


Easy Swagger and Swagger UI in Java EE.

Build Status Maven Central License Javadocs


Twitter URL

Quick Start

Apiee creates swagger documentation from your JAX-RS and Swagger annotations in Runtime. It also give you a custom Swagger UI screen.

The apiee-core library is published to maven central and artefacts is available in Nexus OSS

In your pom.xml:

 <!-- Apiee -->

In you JAX-RS Application class:

@SwaggerDefinition (info = @Info (
                    title = "Example Service",
                    description = "A simple example of apiee",
                    version = "1.0.0",
                    contact = @Contact (
                        name = "Phillip Kruger", 
                        email = "", 
                        url = ""
public class ApplicationConfig extends Application {


You can also set the @SwaggerDefinition part in (more about that later)

In your JAX-RS Endpoint class:

@Api(value = "Example service")
public class ExampleService {
    @ApiOperation(value = "Retrieve some example content", notes = "This will return some json to the client",response = JsonObject.class)
    public Response getExample(){
        JsonObject jsonObject = Json.createObjectBuilder().add("name", "apiee example").add("url", "").build();
        log.log(Level.INFO, "GET: {0}", jsonObject);
        return Response.ok(jsonObject).build();

You can then go to the apiee swagger-ui :



You can add security using the normal Swagger annotation, or some properties in or a combination of both.

Basic Auth example:

As annotation:

@SwaggerDefinition (securityDefinition = 
    @SecurityDefinition(basicAuthDefinitions = @BasicAuthDefinition(key = "basic",description = "foo"))

Or in

securityBasicAuthDesc=foo # Optional

API Key example

As annotation:

@SwaggerDefinition (securityDefinition = 
    @SecurityDefinition(apiKeyAuthDefinitions = @ApiKeyAuthDefinition(key = "api" , name="Authorization", in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER))

Or in

securityApiKeyIn=HEADER # Optional. Default is HEADER. (HEADER/QUERY)
securityApiKeyDesc=foo # Optional
securityApiKeyName=Authorization # Optional. Authorization

OAuth 2 example

As annotation:

@SwaggerDefinition (securityDefinition = 
    @SecurityDefinition(oAuth2Definitions = @OAuth2Definition(key="oauth2",
                                authorizationUrl = "/auth",
                                description = "Bla bla bla",
                                flow = OAuth2Definition.Flow.PASSWORD,
                                scopes = @Scope(name = "scopename",description = "the scope"),
                                tokenUrl = "/auth/token"))

Or in

securityOAuth2Scopes=scopename:the scope,anotherName:the other scope # Comma-seperated with name:description
securityOAuth2Desc=bla bla bla

(above: an API key example)


Apiee comes out of the box with it's own themed swagger ui. However, you might not want a monkey's face on you API documentation, so Apiee makes it easy to whitelabel the UI.

(above: default theme out-of-the-box)

In your web app /src/main/resources you can include the following files:

  • apiee.png
  • apiee.css
  • apiee.html

Variables (

The HTML template that creates the Swagger UI has some variables that you can define in a properties

copyrighBy=John Smith
title=Company X
jsonButtonCaption=download json
yamlButtonCaption=download yaml

There are also some Swagger UI parameters (with default values) that you can include changing (below contains the default values):

supportedSubmitMethods=['get', 'post', 'put', 'delete']

And some OAuth parameters (below contains the default values):


If you want more customization, you can include your own template (apiee.html), see Template section below.

You can also define the @SwaggerDefinition in the with the following properties (so then you can omit it from the source code annotation). NOTE: all properties are optional.

infoTitle=Company X Services
infoDescription=REST API of Company X
infoContactName=Phillip Kruger
infoLicenseName=Apache License, Version 2.0
infoTermsOfService=Some terms here
schemes=HTTP,HTTPS # valid values: HTTP,HTTPS,WS,WSS # if ommited, will figure this out based on headers and server
tags=example:example description,foo,bar

Theme (apiee.css)

Apiee includes swagger-ui-themes and use the muted theme as default. You can override the theme by setting the swaggerUiTheme in the (see above). You can also include your own CSS called apiee.css to style the UI. Themes available from swagger-ui-themes:

  • feeling-blue
  • flattop
  • material
  • monokai
  • muted
  • newspaper
  • outline

(above: some variables and theme changed)

Logo (apiee.png)

To replace the default monkey face logo, include the apiee.png file

(above: logo changed)

Template (apiee.html)

(Advanced) Lastly, if you want even more customization, you can provide you own HTML template to override the default default. This allows you to really change the Look and Feel of you Swagger UI

(above: custome html template)

Application Servers

Apiee has been tested using the following Java EE 7 application servers:

Via a Proxy

You can set some headers to create the correct URL in swagger documents and to make the the UI works. This is handy if the request is going through a proxy.

  • x-request-uri (if this is set, the path part of the URL will be set to this)
  • x-forwarded-port (if this is set, the port part of the URL will be set to this)
  • x-forwarded-host (if this is set, the host part of the URL will be set to this)
  • x-forwarded-proto (if this is set, the scheme or protocol part of the URL will be set to this)


The generation of the swagger document happens at first request and are cached per url for the lifetime of the running server (Application Scoped)

You can clear the cache in the following ways:

You can also see the time that the document has been created in the footer of the swagger UI screen.

Other usefull REST endpoints that might help with debugging:

  "date": "Fri Apr 20 14:06:00 SAST 2018",
  "formattedDate": "2018/04/20 2:06 PM"
    "hash": 1912183572,
    "generatedOn": "Fri Apr 20 14:06:00 SAST 2018",
    "url": "http://localhost:8080/apiee-example/api/apiee/swagger.json"

Blog entry

Also see this blog entry

Documentation available here: