原文出處： oKong
前言
前一章節(jié)介紹了mybatisPlus的集成和簡單使用费奸，本章節(jié)開始接著上一章節(jié)的用戶表，進行Swagger2的集成。現(xiàn)在都奉行前后端分離開發(fā)和微服務(wù)大行其道懒豹，分微服務(wù)及前后端分離后芙盘，前后端開發(fā)的溝通成本就增加了。所以一款強大的RESTful API文檔就至關(guān)重要了脸秽。而目前在后端領(lǐng)域儒老，基本上是Swagger的天下了。
Swagger2介紹
Swagger是一款RESTful接口的文檔在線自動生成豹储、功能測試功能框架贷盲。一個規(guī)范和完整的框架，用于生成剥扣、描述巩剖、調(diào)用和可視化RESTful風格的Web服務(wù)，加上swagger-ui钠怯，可以有很好的呈現(xiàn)佳魔。
SpringBoot集成
這里選用的swagger版本為：2.8.0
0.pom依賴
<!--swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
1.編寫配置文件(Swagger2Config.java)
主要是添加注解@EnableSwagger2和定義Docket的bean類。
@EnableSwagger2
@Configuration
public class SwaggerConfig {
//是否開啟swagger晦炊，正式環(huán)境一般是需要關(guān)閉的鞠鲜，可根據(jù)springboot的多環(huán)境配置進行設(shè)置
@Value(value = "${swagger.enabled}")
Boolean swaggerEnabled;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
// 是否開啟
.enable(swaggerEnabled).select()
// 掃描的路徑包
.apis(RequestHandlerSelectors.basePackage("cn.lqdev.learning.springboot.chapter10"))
// 指定路徑處理PathSelectors.any()代表所有的路徑
.paths(PathSelectors.any()).build().pathMapping("/");
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SpringBoot-Swagger2集成和使用-demo示例")
.description("oKong | 趔趄的猿")
// 作者信息
.contact(new Contact("oKong", "https://blog.lqdev.cn/", "499452441@qq.com"))
.version("1.0.0")
.build();
}
}
3.添加文檔內(nèi)容(一般上是在Controller，請求參數(shù)上進行注解断国，這里以上章節(jié)的UserController進行配置)
UserController
/**
* 用戶控制層 簡單演示增刪改查及分頁
* 新增了swagger文檔內(nèi)容 2018-07-21
* @author oKong
*
*/
@RestController
@RequestMapping("/user")
@Api(tags="用戶API")
public class UserController {
@Autowired
IUserService userService;
@PostMapping("add")
@ApiOperation(value="用戶新增")
//正常業(yè)務(wù)時贤姆， 需要在user類里面進行事務(wù)控制，控制層一般不進行業(yè)務(wù)控制的稳衬。
//@Transactional(rollbackFor = Exception.class)
public Map<String,String> addUser(@Valid @RequestBody UserReq userReq){
User user = new User();
user.setCode(userReq.getCode());
user.setName(userReq.getName());
//由于設(shè)置了主鍵策略 id可不用賦值 會自動生成
//user.setId(0L);
userService.insert(user);
Map<String,String> result = new HashMap<String,String>();
result.put("respCode", "01");
result.put("respMsg", "新增成功");
//事務(wù)測試
//System.out.println(1/0);
return result;
}
@PostMapping("update")
@ApiOperation(value="用戶修改")
public Map<String,String> updateUser(@Valid @RequestBody UserReq userReq){
if(userReq.getId() == null || "".equals(userReq.getId())) {
throw new CommonException("0000", "更新時ID不能為空");
}
User user = new User();
user.setCode(userReq.getCode());
user.setName(userReq.getName());
user.setId(Long.parseLong(userReq.getId()));
userService.updateById(user);
Map<String,String> result = new HashMap<String,String>();
result.put("respCode", "01");
result.put("respMsg", "更新成功");
return result;
}
@GetMapping("/get/{id}")
@ApiOperation(value="用戶查詢(ID)")
@ApiImplicitParam(name="id",value="查詢ID",required=true)
public Map<String,Object> getUser(@PathVariable("id") String id){
//查詢
User user = userService.selectById(id);
if(user == null) {
throw new CommonException("0001", "用戶ID：" + id + "霞捡，未找到");
}
UserResp resp = UserResp.builder()
.id(user.getId().toString())
.code(user.getCode())
.name(user.getName())
.status(user.getStatus())
.build();
Map<String,Object> result = new HashMap<String,Object>();
result.put("respCode", "01");
result.put("respMsg", "成功");
result.put("data", resp);
return result;
}
@GetMapping("/page")
@ApiOperation(value="用戶查詢(分頁)")
public Map<String,Object> pageUser(int current, int size){
//分頁
Page<User> page = new Page<>(current, size);
Map<String,Object> result = new HashMap<String,Object>();
result.put("respCode", "01");
result.put("respMsg", "成功");
result.put("data", userService.selectPage(page));
return result;
}
}
UserReq.java
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
//加入@ApiModel
@ApiModel
public class UserReq {
@ApiModelProperty(value="ID",dataType="String",name="ID",example="1020332806740959233")
String id;
@ApiModelProperty(value="編碼",dataType="String",name="code",example="001")
@NotBlank(message = "編碼不能為空")
String code;
@ApiModelProperty(value="名稱",dataType="String",name="name",example="oKong")
@NotBlank(message = "名稱不能為空")
String name;
}
Swagger訪問與使用
api首頁路徑：http://127.0.0.1:8080/swagger-ui.html
調(diào)試：點擊需要訪問的api列表，點擊try it out!按鈕薄疚，即可彈出一下頁面：
執(zhí)行：
結(jié)果：
大家可下載示例碧信，查看自定義的字符出現(xiàn)的位置，這樣可以對其有個大致了解街夭，各字段的作用領(lǐng)域是哪里砰碴。
Swagger常用屬性說明
常用的注解@Api、@ApiOperation板丽、@ApiModel呈枉、@ApiModelProperty示例中有進行標注，對于其他注解埃碱，大家可自動谷歌碴卧，畢竟常用的就這幾個了。有了swagger之后乃正，原本一些post請求需要postman這樣的調(diào)試工具來進行發(fā)起，而現(xiàn)在直接在頁面上就可以進行調(diào)試了婶博，是不是很爽瓮具！對于服務(wù)的調(diào)用者而已，有了這份api文檔也是一目了然，不需要和后端多少溝通成本名党，按著api說明進行前端開發(fā)即可叹阔。
總結(jié)
本章節(jié)主要是對Swagger的集成和簡單使用進行了說明，詳細的用法传睹，可自行搜索相關(guān)資料下耳幢，這里就不闡述了。因為對于百分之八十之上的文檔要求基本能滿足了欧啤。一些比如前端根據(jù)swagger的api-docs進行前端的快速開發(fā)睛藻，這就需要實際情況實際約定了，比如快速的生成表單頁等也是很方便的事情邢隧。最后店印，強烈建議在生產(chǎn)環(huán)境關(guān)閉swagger,避免不必要的漏洞暴露！
最后
目前互聯(lián)網(wǎng)上很多大佬都有SpringBoot系列教程倒慧，如有雷同按摘，請多多包涵了。本文是作者在電腦前一字一句敲的纫谅，每一步都是實踐的炫贤。若文中有所錯誤之處，還望提出付秕，謝謝兰珍。
