Spring Boot 2.x 集成 springfox-swagger2 構建 RESTful API 文檔實戰教程

Spring Boot 2.x + Swagger 2 整合指南

Spring Boot 簡化了自動配置，集成步驟與 Spring MVC 大同小異，核心差異在於無需 XML 配置、使用 `@RestController` 簡化控制器開發。

Maven 依賴

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.4.0</version>
</dependency>

Swagger 配置類

@Configuration
@EnableSwagger2
public class Swagger2Configuration {

    @Bean
    public Docket buildDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(buildApiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.xingguo.springboot.controller"))
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo buildApiInfo() {
        return new ApiInfoBuilder()
            .title("xingguo 大標題")
            .description("springboot swagger2")
            .termsOfServiceUrl("https://blog.csdn.net/u014231523")
            .contact(new Contact("diaoxingguo", "https://blog.csdn.net/u014231523", "diaoxingguo@163.com"))
            .build();
    }
}

注意：`new ApiInfo()` 已棄用，統一使用 `ApiInfoBuilder` 鏈式構建。

訪問入口

默認端口 8080，配置 `server.port=9090` 後訪問：
https://localhost:9090/swagger-ui.html#/

@RestController 簡化開發

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Controller
@ResponseBody  // 關鍵：組合註解，方法默認返回 JSON
public @interface RestController {
    String value() default "";
}

**優勢**：類級別自動加 `@ResponseBody`，無需每個方法添加，要求 Spring 4.0.1+。

Controller 實戰：完整註解示例

@RestController
@Api(value = "用戶控制器", description = "用戶操作", tags = {"用戶操作接口"})
public class UserController {

    @Resource
    private UserService userService;

    @ApiOperation("獲取用戶信息")
    @GetMapping("/getUserInfo")
    public User getUserInfo(
        @ApiParam(name = "id", value = "用戶ID", required = true) Long id,
        @ApiParam(name = "username", value = "用戶名") String username) {
        return userService.getUserInfo();
    }

    @ApiOperation("更改用戶信息")
    @PostMapping("/updateUserInfo")
    public int updateUserInfo(
        @RequestBody @ApiParam(name = "用戶對象", value = "傳入JSON", required = true) User user) {
        return userService.updateUserInfo(user);
    }

    @ApiOperation("添加用戶信息")
    @PostMapping("/saveUser")
    public String saveUser(
        @RequestBody @ApiParam(name = "user", value = "JSON格式", required = true) User user) {
        userService.saveUser(user);
        return "success";
    }
}

實體類註解：@ApiModel + @ApiModelProperty

@ApiModel(description = "用戶對象")
public class User {
    @ApiModelProperty(value = "用戶名", name = "username")
    private String username;

    @ApiModelProperty(value = "狀態", name = "state", required = true)
    private Integer state;

    @ApiModelProperty(value = "密碼", hidden = true) // 隱藏敏感字段
    private String password;
    // 其他字段、getter/setter 省略
}

單參數接口文檔效果

`@ApiParam(required = true)` 會在 UI 顯示「required」標識。

核心功能亮點

• 在線調試：點擊 "Try it out" 直接發送請求查看響應
• 模型自動生成：實體類註解自動轉為 JSON Schema
• 分組標籤：`tags` 實現接口分類管理
• 參數驗證提示：`required`、`example`、`allowableValues` 豐富文檔

遷移建議

Springfox 已停止維護，新項目推薦使用 **SpringDoc OpenAPI 3**（`springdoc-openapi-starter-webmvc-ui`），原生支持 OpenAPI 3.0、Spring Boot 3、Kotlin、WebFlux，註解兼容性良好（`@Operation`、`@Parameter`、`@Schema` 等）。