Master the Updated Spring Boot Swagger Starter with Pure Configuration

This Swagger starter has existed for four years, created because the official Swagger project did not provide a Spring Boot‑style starter, requiring extensive Java configuration; the starter moves most of that configuration into property files.

The starter has gained over 2k stars and more than 3.1k uses.

Repository: https://github.com/SpringForAll/spring-boot-starter-swagger

Update Content

Upgrade the springfox Swagger dependency to 3.0.0.

Control documentation enable/disable via the springfox.documentation.enabled parameter.

How to Use

Integrate Swagger into a Spring Boot project in two steps:

Add the dependency to pom.xml:

<dependency>
  <groupId>com.spring4all</groupId>
  <artifactId>swagger-spring-boot-starter</artifactId>
  <version>2.0.0.RELEASE</version>
</dependency>

Note

From version 1.6.0 the artifactId was changed to swagger-spring-boot-starter for Spring Boot 1.6.0 and later; earlier versions keep spring-boot-starter-swagger.

From version 2.0.0 the @EnableSwagger2Doc annotation is no longer required to start Swagger configuration.

By default, all request mappings loaded by Spring MVC are documented.

Parameter Configuration

Detailed configuration options are shown below.

Configuration Example

springfox.documentation.enabled=true

swagger.title=spring-boot-starter-swagger
swagger.description=Starter for swagger 2.x
swagger.version=1.4.0.RELEASE
swagger.license=Apache License, Version 2.0
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
swagger.contact.name=didi
swagger.contact.url=http://blog.didispace.com
[email protected]
swagger.base-package=com.didispace
swagger.base-path=/**
swagger.exclude-path=/error, /ops/**

swagger.globalOperationParameters[0].name=name one
swagger.globalOperationParameters[0].description=some description one
swagger.globalOperationParameters[0].modelRef=string
swagger.globalOperationParameters[0].parameterType=header
swagger.globalOperationParameters[0].required=true
swagger.globalOperationParameters[1].name=name two
swagger.globalOperationParameters[1].description=some description two
swagger.globalOperationParameters[1].modelRef=string
swagger.globalOperationParameters[1].parameterType=body
swagger.globalOperationParameters[1].required=false

// Disable default response messages and define custom ones
swagger.apply-default-response-messages=false
swagger.global-response-message.get[0].code=401
swagger.global-response-message.get[0].message=401get
swagger.global-response-message.get[1].code=500
swagger.global-response-message.get[1].message=500get
swagger.global-response-message.get[1].modelRef=ERROR
swagger.global-response-message.post[0].code=500
swagger.global-response-message.post[0].message=500post
swagger.global-response-message.post[0].modelRef=ERROR

Configuration Explanation

springfox.documentation.enabled=Whether to enable Swagger, default: true

swagger.title=Title
swagger.description=Description
swagger.version=Version
swagger.license=License
swagger.licenseUrl=License URL
swagger.termsOfServiceUrl=Terms of Service URL

swagger.contact.name=Maintainer
swagger.contact.url=Maintainer URL
swagger.contact.email=Maintainer email

swagger.base-package=Base package for scanning, default: all
swagger.base-path=Base URL pattern, default: /**
swagger.exclude-path=Exclude URL pattern, default: none

swagger.host=Host information for the docs, default: none

swagger.globalOperationParameters[0].name=Parameter name
swagger.globalOperationParameters[0].description=Description
swagger.globalOperationParameters[0].modelRef=Parameter type
swagger.globalOperationParameters[0].parameterType=Location (header, query, path, body, form)
swagger.globalOperationParameters[0].required=Whether required (true/false)

1.3.0.RELEASE added swagger.host property, also supports docket configuration. 1.4.0.RELEASE added: swagger.enabled : switch to turn Swagger on/off. swagger.globalOperationParameters : set global parameters such as header tokens; supports docket configuration. 2.0.0.RELEASE changed the enable switch to springfox.documentation.enabled .

Path Rule Explanation

The swagger.base-path and swagger.exclude-path use ANT patterns.

Use swagger.base-path to define the base URL pattern for documentation generation, and swagger.exclude-path to exclude specific paths.

Example configuration:

management.context-path=/ops

swagger.base-path=/**
swagger.exclude-path=/ops/**, /error

This setup documents all paths except those starting with /ops/ and the default Spring Boot /error endpoint.

Group Configuration

When an API has many endpoints, you can group the documentation. Grouping is supported from version 1.2.0.RELEASE.

Group configuration example:

swagger.docket.aaa.title=group-a
swagger.docket.aaa.description=Starter for swagger 2.x
swagger.docket.aaa.version=1.3.0.RELEASE
swagger.docket.aaa.termsOfServiceUrl=https://gitee.com/didispace/spring-boot-starter-swagger
swagger.docket.aaa.contact.name=zhaiyongchao
swagger.docket.aaa.contact.url=http://spring4all.com/
[email protected]
swagger.docket.aaa.excludePath=/ops/**
swagger.docket.aaa.globalOperationParameters[0].name=name three
swagger.docket.aaa.globalOperationParameters[0].description=some description three override
swagger.docket.aaa.globalOperationParameters[0].modelRef=string
swagger.docket.aaa.globalOperationParameters[0].parameterType=header

swagger.docket.bbb.title=group-bbb
swagger.docket.bbb.basePackage=com.yonghui

Default configuration and group configuration can be combined; group settings inherit unspecified values from the default configuration.

JSR‑303 Validation Annotation Support (1.5.0+)

The starter displays JSR‑303 validation annotations in the generated docs:

@NotNull

@Max

,

@Min

@Size

@Pattern

Custom Global Response Message Configuration (1.6.0+)

Supports custom global response messages for all HTTP methods:

// Disable default response messages and define custom ones
swagger.apply-default-response-messages=false
swagger.global-response-message.get[0].code=401
swagger.global-response-message.get[0].message=401get
swagger.global-response-message.get[1].code=500
swagger.global-response-message.get[1].message=500get
swagger.global-response-message.get[1].modelRef=ERROR
swagger.global-response-message.post[0].code=500
swagger.global-response-message.post[0].message=500post
swagger.global-response-message.post[0].modelRef=ERROR

UI Function Configuration (1.6.0+)

Control the “try it out” button via swagger.ui-config.submit-methods. swagger.ui-config.submit-methods=get,delete Set an empty value to disable the debug button: swagger.ui-config.submit-methods= Other UI settings:

# JSON editor
swagger.ui-config.json-editor=false

# Show request headers
swagger.ui-config.show-request-headers=true

# Request timeout (ms)
swagger.ui-config.request-timeout=5000

ignoredParameterTypes Configuration (1.6.0+)

# Global configuration
swagger.ignored-parameter-types[0]=com.didispace.demo.User
swagger.ignored-parameter-types[1]=com.didispace.demo.Product

# Group configuration
swagger.docket.aaa.ignored-parameter-types[0]=com.didispace.demo.User
swagger.docket.aaa.ignored-parameter-types[1]=com.didispace.demo.Product

When recursive object definitions cause infinite loops in schema generation, you can ignore offending classes via ignoredParameterTypes .

Authorization Configuration (1.7.0+)

Added Authorization configuration items.

# Authorization strategy ID, corresponds to SecurityReferences ID
swagger.authorization.name=Authorization

# Authorization type: ApiKey | BasicAuth | None (default ApiKey)
swagger.authorization.type=ApiKey

# Header name for token transmission
swagger.authorization.key-name=token

# Regex to enable authorization for matching URLs (default ^.*$ matches all)
swagger.authorization.auth-regex=^.*$

Supported types: ApiKey, BasicAuth, None (default ApiKey). Future support for Oauth2 is planned.

Global security references are enabled by default; no extra parameters are required. The auth-regex parameter controls the scope of global authorization via regular expressions. In addition to the global switch, you can annotate @Authorization on @RestController methods to define per‑endpoint security.

// Example of method-level authorization
@ApiOperation(value = "Hello World", authorizations = {@Authorization(value = "Authorization")})
@RequestMapping(value = "/hello", method = RequestMethod.GET)
String hello();

/**
 * Configure an ApiKey‑based security scheme.
 */
private ApiKey apiKey() {
    return new ApiKey(swaggerProperties().getAuthorization().getName(),
            swaggerProperties().getAuthorization().getKeyName(),
            ApiKeyVehicle.HEADER.getValue());
}

/**
 * Configure the global security context with regex matching.
 */
private SecurityContext securityContext() {
    return SecurityContext.builder()
            .securityReferences(defaultAuth())
            .forPaths(PathSelectors.regex(swaggerProperties().getAuthorization().getAuthRegex()))
            .build();
}

/**
 * Define the default global security references.
 */
private List<SecurityReference> defaultAuth() {
    AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
    AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
    authorizationScopes[0] = authorizationScope;
    return Collections.singletonList(SecurityReference.builder()
            .reference(swaggerProperties().getAuthorization().getName())
            .scopes(authorizationScopes).build());
}