Quickly Add Swagger2 to Spring Boot with Auto-Configuration Starter

Overview

This starter leverages Spring Boot's auto‑configuration to integrate Swagger 2 with minimal boilerplate, automatically generating API documentation for all Spring MVC request mappings.

Supported Versions

Spring Boot 1.5.x

Swagger 2.7.x

Dependency

<dependency>
  <groupId>com.didispace</groupId>
  <artifactId>spring-boot-starter-swagger</artifactId>
  <version>1.2.0.RELEASE</version>
</dependency>

Enable Swagger

@EnableSwagger2Doc
@SpringBootApplication
public class Bootstrap {
    public static void main(String[] args) {
        SpringApplication.run(Bootstrap.class, args);
    }
}

Default Behavior

When the starter is on the classpath, all request mappings discovered by Spring MVC are included in the generated Swagger documentation without additional configuration.

Configuration Properties

Properties can be defined in application.properties or application.yml to customize the generated documentation.

swagger.title=spring-boot-starter-swagger
swagger.description=Starter for swagger 2.x
swagger.version=1.1.0.RELEASE
swagger.license=Apache License
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=https://blog.didispace.com
[email protected]
swagger.base-package=com.didispace
swagger.base-path=/**
swagger.exclude-path=/error,/ops/**

Path Rules

The swagger.base-path property defines which request paths are included using Ant‑style patterns, while swagger.exclude-path lists patterns to be omitted. For example, setting swagger.base-path=/** and swagger.exclude-path=/ops/**,/error documents every endpoint except those under /ops/ and the default Spring Boot error endpoint.

Group Configuration (since 1.2.0.RELEASE)

Multiple documentation groups can be defined with the swagger.docket.<name>.* properties. Each group can have its own title, description, version, contact information, base package, and path rules. Properties not specified in a group inherit values from the global configuration.

swagger.docket.aaa.title=group-a
swagger.docket.aaa.description=Starter for swagger 2.x
swagger.docket.aaa.version=1.2.0.RELEASE
swagger.docket.aaa.contact.name=zhaiyongchao
swagger.docket.aaa.contact.url=http://example.com
[email protected]
swagger.docket.aaa.base-package=com.example.groupa
swagger.docket.aaa.base-path=/**
swagger.docket.aaa.exclude-path=/ops/**

swagger.docket.bbb.title=group-b
swagger.docket.bbb.base-package=com.example.groupb

Inheritance

Any property omitted in a specific group falls back to the default configuration, allowing shared settings while still supporting per‑group overrides.