swagger-ui-integration

Swagger core and Swagger UI integration effortless for Java EE application

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 :

Annotation @SwaggerUIConfiguration
resource Configuration file swagger-project.properties allow set configuration during package building.
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 :

swagger documentation file : http://localhost/customer/api/swagger (according the @ApplicationPath value.
swagger UI site : http://localhost/customer/api-docs/ or http://localhost/customer/api-docs/index.html

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+

Tibor17/swagger-ui-integration

swagger-ui-integration

swagger-ui-integration ?

Use