Skip to content
Simplifies the setup of Springfox.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.mvn/wrapper
src
.gitignore
.travis.yml
LICENSE.txt
README.md
mvnw
mvnw.cmd
pom.xml

README.md

Springfox Loader

Build Status Coverage Status

Simplifies the initialization of Springfox. It does not offer all the flexibility and configuration options available in Springfox, but is created to be a simple way to get spring + swagger up and running without the need for a lot of configuration.

Features:

  • Annotation-based configuration
  • Support for standard Spring application-configuration in properties/yml files
  • Support for using Spring placeholder values ${...} in the configuration
  • Easy to extend by using the standard Springfox classes
  • Convention based naming of values displayed in swagger-ui, minimizing the need for manual configuration

Installation

The required springfox dependencies are included when you add the Springfox Loader dependency.

The jar-file available in JCenter.

Gradle

build.gradle

compile('com.github.springfox.loader:springfox-loader:2.0.0')

Maven

pom.xml

<dependency>
    <groupId>com.github.springfox.loader</groupId>
    <artifactId>springfox-loader</artifactId>
    <version>2.0.0</version>
</dependency>

Usage

Add @EnableSpringfox to the class containing the Spring boot main method (@SpringBootApplication). This will automatically create the springfox configuration for you.

The required values in the @EnableSpringfox is title and version. You can set these values either by using @Info or with the properties springfox.title and springfox.version.

It is also possible to add Spring placeholders (with the ${...} syntax) as values in the annotation. This can be useful if you want to add values that are defined in for example properties/yml files. In the example below the value ${version} can be added in for example the application.properties-file

Minimal examples

@EnableSpringfox(
       @Info(title = "title", version = "${version}")
)

or add configuration properties

springfox.title=my-app
springfox.version=1.0.0
@EnableSpringfox

Full example

@EnableSpringfox(
    convention = false,
    swaggerUiBasePath = "",
    includeControllers = MyController.class,    
    value = @Info(
         title = "",
         version = "",
         description = "",
         termsOfService = "",
         contact = @Contact(name = "", url = "", email = ""),
         license = @License(name = "", url = ""),
         extensions = @Extension(name = "x-test",
            properties = @ExtensionProperty(name = "test-key", value = "test-value")
         ))
)
  • Use convention to print better names on the swagger-ui page. It will split the operation name by replacing camelcase with space and uppercasing the word (for example the method getCustomer() will be displayed as Get customer). If the @ApiOperation annotation is present, these values will be used.
  • swaggerUiBasePath customize the base path to swagger-ui. If the value is for example '/documentation', the path to swagger-ui will be '/documentation/swagger-ui.html'.
  • includeControllers add controllers to the swagger configuration that is not registered in the default base package (which is based on the Application class).

Properties

It is also possible to configure the values using properties/yml files (typically application.properties / application.yml). On startup it will try to lookup the same configuration options as described above with 'springfox.' as a prefix. For example springfox.path.

If both the annotation values and properties values are defined the values from the properties/yml-file is used.

Application properties

  • springfox.path
  • springfox.title or spring.application.name
  • springfox.description
  • springfox.version
  • springfox.terms-of-service-url
  • springfox.contact.name
  • springfox.contact.url
  • springfox.contact.email
  • springfox.license.name
  • springfox.license.url
  • springfox.profiles - Enable springfox for the configured profiles. If not set, all profiles loads springfox. Default is all profiles.
  • springfox.swagger-ui-base-path

Swagger UI

The swagger-ui dependency is already included by Springfox Loader. After enabling Springfox Loader you can access the webpage: http://localhost:8080/swagger-ui.html
The base path to swagger-ui can be customized with the springfox.swagger-ui-base-path.

A list of the swagger resources are available here: http://localhost:8080/swagger-resources

Custom options

If there are options that are available in Springfox, but not the Springfox-loader it is possible to add it manually. You can simply autowire the Docket-object and can alter the setup as needed.

@Autowired
private Docket docket;

@PostConstruct
public void init() {
    docket.apiInfo(new ApiInfo("My new title", "", "1.0.0", "", new Contact("", "", ""), "", ""));
}

References

You can’t perform that action at this time.