SpringFox 3.0.0 Quick Guide: Swagger Integration for Spring Boot

SpringFox 3.0.0 was released, the first major version after 2.9.2, offering a starter for Swagger integration in Spring MVC applications.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
    <scope>compile</scope>
</dependency>

Previously a custom starter was created at https://github.com/SpringForAll/spring-boot-starter-swagger . The new SpringFox starter brings many improvements.

Spring 5 and WebFlux support (request mapping only)

Spring Integration support

Spring Boot auto‑configuration via springfox-boot-starter Auto‑completion for configuration properties

Better specification compatibility

Support for OpenAPI 3.0.3

Almost zero external dependencies (only spring‑plugin and swagger‑core)

Existing Swagger 2 annotations remain valid and are enriched for OpenAPI 3

Key highlights of this release are WebFlux support, OpenAPI 3 compatibility, and seamless upgrade from Swagger 2.

Getting Started

Step 1: Create a Spring Boot project.

Step 2: Add the starter dependency to pom.xml:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

Step 3: Enable OpenAPI in the main class:

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

Step 4: Add example controller methods:

@Api(tags="User Management")
@RestController
public class UserController {

    @ApiOperation("Create User")
    @PostMapping("/users")
    public User create(@RequestBody @Valid User user) {
        return user;
    }

    @ApiOperation("User Details")
    @GetMapping("/users/{id}")
    public User findById(@PathVariable Long id) {
        return new User("bbb", 21, "Shanghai", "[email protected]");
    }

    @ApiOperation("User List")
    @GetMapping("/users")
    public List<User> list(@ApiParam("Page index") @RequestParam int pageIndex,
                           @ApiParam("Page size") @RequestParam int pageSize) {
        List<User> result = new ArrayList<>();
        result.add(new User("aaa", 50, "Beijing", "[email protected]"));
        result.add(new User("bbb", 21, "Guangzhou", "[email protected]"));
        return result;
    }

    @ApiIgnore
    @DeleteMapping("/users/{id}")
    public String deleteById(@PathVariable Long id) {
        return "delete user : " + id;
    }
}

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("User Basic Info")
public class User {
    @ApiModelProperty("Name")
    @Size(max = 20)
    private String name;
    @ApiModelProperty("Age")
    @Max(150)
    @Min(1)
    private Integer age;
    @NotNull
    private String address;
    @Pattern(regexp = "^[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)+$")
    private String email;
}

Step 5: Run the application and open the Swagger UI at http://localhost:8080/swagger-ui/index.html.

Note: The default Swagger UI path http://host/context-path/swagger-ui.html has been removed. New paths are http://host/context-path/swagger-ui/index.html and http://host/context-path/swagger-ui/ . With log level adjustments you can see both the old /v2/api-docs endpoint and the new /v3/api-docs endpoint for OpenAPI 3.

Related example code can be found in the chapter2-7 directory of the following repositories:

GitHub: https://github.com/dyc87112/SpringBoot-Learning/

Gitee: https://gitee.com/didispace/SpringBoot-Learning/