Quickly Add Swagger2 API Docs to Spring Boot with the Swagger Starter

Overview

The Spring Boot Starter for Swagger simplifies the integration of Swagger‑2 into Spring Boot applications by providing auto‑configuration and a set of configurable properties.

What’s New in 1.3.0.RELEASE

Added swagger.host configuration to set the host of the generated API docs.

Added support for JSR‑303 validation annotations (@NotNull, @Max, @Min, @Size, @Pattern) in the documentation.

Getting Started

Add the starter dependency to your pom.xml:

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

Enable the starter in your main application class:

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

Configuration

All properties are prefixed with swagger.. Example:

swagger.title=Spring‑Boot‑Starter‑Swagger
swagger.description=Starter for swagger 2.x
swagger.version=1.3.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.host=api.example.com

Path rules use Ant‑style patterns. For example, to document all endpoints except actuator and custom monitoring paths:

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

Grouping

From version 1.2.0.RELEASE you can define multiple documentation groups using swagger.docket.<name>.* properties. 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=https://spring4all.com/
[email protected]
swagger.docket.aaa.base-package=com.yonghui
swagger.docket.bbb.title=group-b

Properties not defined in a group fall back to the default configuration.

JSR‑303 Annotation Support

The starter renders validation constraints from annotations such as @NotNull, @Max, @Min, @Size, and @Pattern in the generated Swagger UI.

Resources

GitHub: https://github.com/dyc87112/spring-boot-starter-swagger

Gitee: https://gitee.com/didispace/spring-boot-starter-swagger

Demo project: https://github.com/dyc87112/swagger-starter-demo

Author blog: http://blog.didispace.com

Community: http://spring4all.com