Swagger core and Swagger UI integration effortless for Java EE application
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src/main Clean imports Mar 21, 2016
.gitignore Initialization Mar 1, 2016
.travis.yml Update .travis.yml Mar 3, 2016
LICENSE Initial commit Feb 29, 2016
README.md Update version - by Tibor17 May 12, 2018
pom.xml New Relase with swagger-ui:3.x.x May 11, 2018
swaggerUIConfig.properties refactoring test Mar 6, 2016

README.md

swagger-ui-integration

Swagger core and Swagger UI integration effortless for Java EE application


Build Status Maven Central


swagger-ui-integration ?

swagger-ui-integration is a library that allows you to turn at the same time exposing the description of the REST API of the application via the swagger and offer access a UI (swagger-UI) using descriptive swagger thereof.

swagger lib linked :

  • swaggerUI : 3.14.1 (thx to Tibor17)
  • swagger-core : 1.5.19 (thx to Tibor17)

demo : examples how to use swagger-ui-integration lib on github

Since version 0.8, you can reach the library from maven central repository.

###Use Swagger core and Swagger UI in your project.

The library provides a number of default values and get 3 levels of configuration.

Configurations path - order of configuration items reading :

  1. Annotation @SwaggerUIConfiguration
  2. resource Configuration file swagger-project.properties allow set configuration during package building.
  3. system configuration file store in system property. The system property'name must be set in systemPropertyForExternalConfigurationFilename

annotation properties and default values :

  • active : Access to the description of the REST API via Swagger and activate swagger description.
    • default value : true
  • configurationFilename : Default resource file store swagger-ui-integration configuration
    • default value : swagger-project.properties
  • systemPropertyForExternalConfigurationFilename : property system name storing the full path to the external configuration file for swagger-ui-integration.
    • default value was empty, if you want a external configuration name, you must set one.
  • host : your default host. if it is not assigned, it will be determined in the first call.
  • restApplicationPackageAsRoot : use the class use JAX-RS @ApplicationPath package. If false, you must set restApplicationPackage
    • default value : true
  • restApplicationPackage : Base package REST application - used only if the restApplicationClass was undefined.
    • by default empty, the process take class path from @SwaggerUIConfiguration annoted class package.
  • apiDocPath : API documentation sub-path
    • default value : /api-docs
  • apiDocIndex : resource fully qualified filename for replace default index.html used by.
    • default value : not fixed - use default swagger-ui-integration index.html (hide url field).
    • see below for more explaination for your own index file

configuration files properties and default values :

All property must used prefixe swagger. (i.e. swagger.apiDocPath). You can store your swagger properties in overall project configuration file.

  • swagger.active : Access to the description of the REST API via Swagger and activate swagger description.
  • swagger.systemPropertyForExternalConfigurationFilename : property system name storing the full path to the external configuration file for swagger-ui-integration.
  • swagger.host : your default host. if it is not assigned, it will be determined in the first call.
  • swagger.restApplicationClass : class wear @ApplicationPath JAX-RS annotation.
  • swagger.restApplicationPackageAsRoot : use the class use JAX-RS @ApplicationPath package. If false, you must set swagger.restApplicationPackage
  • swagger.restApplicationPath : Base path for REST application - used only if the restApplicationClass was undefined.
  • swagger.restApplicationPackage : Base package REST application - used only if the restApplicationClass was undefined.
  • swagger.apiDocPath : API documentation sub-path
  • swagger.apiDocIndex : resource fully qualified filename for replace default index.html used by.

how use it

First add dependency to your JavaEE project :

    <dependencies>
        ...
        <dependency>
            <groupId>org.shipstone</groupId>
            <artifactId>swagger-ui-integration</artifactId>
            <version>1.0</version>
        </dependency>
        ...
    </dependencies>

Add empty class with the annotation @SwaggerUIConfiguration.

@SwaggerUIConfiguration
public class SwaggerURLRewriter  {
}

Your API REST Application class, no need to do anything else :)

@ApplicationPath("api")
public class RestApplication extends Application {
}

And finally, on all your endpoints you want to view in swagger documentation, add specific swagger annotation. Most important is @Api ;)

@Path("person")
@Api(value = "Personne")
@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML, MediaType.TEXT_PLAIN})
public class PersonEndpoint {

  @GET
  @ApiOperation(value = "Liste des personnes")
  @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
  public List<Person> getPersonList() {
    ...
    some stuff
    ...
  }

}

Use

If you use only default configuration, the library give you two url (i.e. use previous exemple and context (project final name) as customer in localhost server :

Activation or desactivation by system configuration file need to relaunch application.

have fun !


####ToDo

  • remove org.ocpsoft.rewrite dependencies - version 0.9
  • use webfragment - Version 0.9
  • ensure compatibility java EE 6 - version 1.0-RC1
  • split the library into 2 sub-module (api & core) (? useful ?) - version 1.0+
  • allow to replace embedded site with a external site - version 1.0+
  • remove support Java EE 6 and Java 1.7, switch to Java EE 7 and Java 1.8 - version 2.0+