JarCastingswagger-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.propertiesallow 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
- default value :
configurationFilename: Default resource file store swagger-ui-integration configuration- default value :
swagger-project.properties
- default value :
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@ApplicationPathpackage. If false, you must setrestApplicationPackage- default value :
true
- default value :
restApplicationPackage: Base package REST application - used only if the restApplicationClass was undefined.- by default empty, the process take class path from
@SwaggerUIConfigurationannoted class package.
- by default empty, the process take class path from
apiDocPath: API documentation sub-path- default value :
/api-docs
- default value :
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@ApplicationPathJAX-RS annotation.swagger.restApplicationPackageAsRoot: use the class use JAX-RS@ApplicationPathpackage. If false, you must setswagger.restApplicationPackageswagger.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-pathswagger.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
@ApplicationPathvalue. - 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+