在前后端分離的大背景下，API接口就成為了連接前后端之間的關鍵紐帶。為了更好管理接口文檔，實現(xiàn)文檔與代碼的同步。這里我們引入、介紹Swagger框架，其可通過注解的方式快速完成接口文檔

添加依賴

在POM添加如下依賴

<!-- Swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.0</version>
</dependency>

配置

Swagger的配置代碼如下所示，可以看到也是很簡單的

/**
 * Swagger Config
 */
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        Docket docket = new Docket(SWAGGER_2)
            // 項目信息
            .apiInfo( apiInfo() )
            // 設置應用上下文
            .pathMapping("/")
            // 是否允許訪問Swagger頁面, 生產(chǎn)環(huán)境需設為false
            .enable( true )
            .select()
            // 按需設置需要生成接口文檔的父包
            .apis(RequestHandlerSelectors.basePackage("com.aaron"))
            .build();
        return docket;
    }

    /**
     * 項目信息
     * @return
     */
    private ApiInfo apiInfo() {
        Contact concat = new Contact("Aaron", null,null);
        return new ApiInfoBuilder()
            .title("Demo服務")    // 標題
            .description("基于SpringBoot的Demo")   // 描述
            .contact(concat)    // 作者信息
            .version("1.2")  // 版本
            .build();
    }

}

在SpringBoot啟動類上添加@EnableSwagger2注解即可

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

由于測試服務運行在8080端口，故打開下面的地址即可看到Swagger的頁面

http://localhost:8080/swagger-ui.html

效果如下

使用

通過Swagger的注解，即可快速便捷的生成接口文檔。示例代碼如下所示

/**
 * 車輛管理 Controller
 */
@RestController
@RequestMapping("car")
@Api(tags = "車輛管理") // 定義Controller說明
public class CarController {

    /**
     * 保存車輛信息
     * @param car
     * @return
     */
    @PostMapping("/save")
    // 定義接口說明
    @ApiOperation(value = "保存車輛信息", notes = "保存(添加/修改)車輛信息")
    public HttpResponseResult<String> save(@RequestBody Car car) {
        return null;
    }

    /**
     * 根據(jù)ID獲取車輛信息
     * @param id
     * @return
     */
    @GetMapping("/findById")
    // 定義接口說明
    @ApiOperation(value = "根據(jù)ID獲取車輛信息")
    public HttpResponseResult<Car> findById(@ApiParam(value="車輛ID", required=true) @RequestParam Integer id) {
        Car car = Car.builder()
            .id(id)
            .build();
        return HttpResponseResult.<Car>builder().data(car).build();
    }

    /**
     * 根據(jù)名稱獲取車輛信息
     * @param name
     * @return
     */
    @GetMapping("/findByName")
    // 定義接口說明
    @ApiOperation(value = "根據(jù)名稱獲取車輛信息")
    @ApiImplicitParam(name = "name",value = "名稱",required = true)
    public HttpResponseResult<Car> findByName(@RequestParam String name) {
        Car car = Car.builder()
            .name( name )
            .build();
        return HttpResponseResult.<Car>builder().data(car).build();
    }

    /**
     * 根據(jù)條件刪除
     * @param name
     * @param id
     * @return
     */
    @GetMapping("/deleteByParam")
    // 定義接口說明
    @ApiOperation(value = "根據(jù)條件刪除")
    @ApiImplicitParams({    // 通過 @ApiImplicitParams 定義多個入?yún)⒄f明
        @ApiImplicitParam(name = "name",value = "名稱",required = true),
        @ApiImplicitParam(name = "id",value = "車輛ID",required = false)
    })
    public HttpResponseResult<Integer> deleteByParam(@RequestParam String name, @RequestParam Integer id) {
        return null;
    }
}

可以看到，對于入?yún)⒄f明的定義，可以通過多種方式，具體包括：@ApiParam、@ApiImplicitParam、@ApiImplicitParams等注解。特別的，對于對象(JSON格式)來說，可以通過@ApiModel、@ApiModelProperty注解定義對象、字段說明

/**
 * 汽車
 */
@AllArgsConstructor
@NoArgsConstructor
@Data
@Builder
@ApiModel("汽車") // 定義對象說明
public class Car {

    /**
     * ID
     */
    // 定義字段說明
    @ApiModelProperty("車輛ID")
    private Integer id;

    /**
     * 名稱
     */
    @ApiModelProperty("名稱")
    private String name;

    /**
     * 價格
     */
    @ApiModelProperty("價格")
    private Double price;

    /**
     * 數(shù)量
     */
    // 通過設置hidden屬性為true, 在接口文檔中隱藏該字段
    @ApiModelProperty(value="數(shù)量", hidden=true)
    private Integer num;

}
...
@AllArgsConstructor
@NoArgsConstructor
@Data
@Builder
@ApiModel("HTTP響應結果")
public class HttpResponseResult<T> {
    @ApiModelProperty("狀態(tài)碼")
    private String code;

    @ApiModelProperty("信息")
    private String msg;

    @ApiModelProperty("數(shù)據(jù)")
    private T data;
}

訪問Swagger頁面，效果如下所示

具體就某個具體的接口來看。一方面，我們可以通過Try it out按鈕對后端服務進行在線測試；另一方面，其對于泛型參數(shù)也是支持的