SpringBoot中Swagger集成
在前后端分離的大背景下，API接口就成為了連接前后端之間的關(guān)鍵紐帶。為了更好管理接口文檔，實(shí)現(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)
// 項(xiàng)目信息
.apiInfo( apiInfo() )
// 設(shè)置應(yīng)用上下文
.pathMapping("/")
// 是否允許訪問Swagger頁面, 生產(chǎn)環(huán)境需設(shè)為false
.enable( true )
.select()
// 按需設(shè)置需要生成接口文檔的父包
.apis(RequestHandlerSelectors.basePackage("com.aaron"))
.build();
return docket;
}
/**
* 項(xiàng)目信息
* @return
*/
private ApiInfo apiInfo() {
Contact concat = new Contact("Aaron", null,null);
return new ApiInfoBuilder()
.title("Demo服務(wù)") // 標(biāo)題
.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);
}
}
由于測試服務(wù)運(yùn)行在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ù)量
*/
// 通過設(shè)置hidden屬性為true, 在接口文檔中隱藏該字段
@ApiModelProperty(value="數(shù)量", hidden=true)
private Integer num;
}
...
@AllArgsConstructor
@NoArgsConstructor
@Data
@Builder
@ApiModel("HTTP響應(yīng)結(jié)果")
public class HttpResponseResult<T> {
@ApiModelProperty("狀態(tài)碼")
private String code;
@ApiModelProperty("信息")
private String msg;
@ApiModelProperty("數(shù)據(jù)")
private T data;
}
訪問Swagger頁面，效果如下所示
具體就某個具體的接口來看。一方面，我們可以通過Try it out按鈕對后端服務(wù)進(jìn)行在線測試；另一方面，其對于泛型參數(shù)也是支持的
評論
圖片
表情