Spring MVC 集成 springfox-swagger2 構建 RESTful API 文檔完整指南

技術選型背景

相比舊版 swagger-springmvc 需手動複製靜態資源，springfox-swagger2 提供開箱即用的 UI 界面，版本 2.4.0 穩定可靠。

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>

Spring MVC 靜態資源映射

<mvc:default-servlet-handler />

確保 Swagger UI 靜態資源（HTML、JS、CSS）正確訪問。

Swagger 配置類

@Configuration
@EnableSwagger2
public class SwaggerConfig {

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

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

關鍵點：

• @EnableSwagger2 啟用自動配置
• Docket 核心配置：文檔類型、API 信息、掃描包路徑、路徑過濾
• ApiInfoBuilder 鏈式構建文檔元信息

訪問入口

啟動項目後訪問：https://{ip}:{port}/{projectName}/swagger-ui.html#/

常用註解詳解

Controller 實戰示例

@Controller
@Api(value = "用戶控制器", description = "用戶相關操作")
public class UserController {

    @RequestMapping(value = "index", method = RequestMethod.POST)
    @ApiOperation(value = "首頁", notes = "跳轉到首頁")
    public Object getIndex(
        @ApiParam(name = "topic實體", value = "json格式", required = true) 
        @RequestBody Topic topic) {
        // 業務邏輯
        return new Object();
    }
}

實體類註解示例

@ApiModel(value = "Topic", description = "主題實體")
public class Topic {
    @ApiModelProperty(value = "標題", required = true)
    private String title;
    
    @ApiModelProperty(value = "內容")
    private String content;
    // getter/setter 省略
}

項目結構參考

遷移到 Spring Boot

Spring Boot 集成方式基本一致，參考《Spring Boot 集成 springfox-swagger2 構建 RESTful API 方法教程》。