SpringBoot | 第十章：Swagger 2 的集成和使用

知識 08-23

（點擊

上方公眾號

，可快速關注）

來源：oKong ，

blog.lqdev.cn/2018/07/21/springboot/chapter-ten/

前言

前一章節介紹了mybatisPlus的集成和簡單使用，本章節開始接著上一章節的用戶表，進行Swagger2的集成。現在都奉行前後端分離開發和微服務大行其道，分微服務及前後端分離後，前後端開發的溝通成本就增加了。所以一款強大的RESTful API文檔就至關重要了。而目前在後端領域，基本上是Swagger的天下了。

Swagger2介紹

Swagger是一款RESTful介面的文檔在線自動生成、功能測試功能框架。一個規範和完整的框架，用於生成、描述、調用和可視化RESTful風格的Web服務，加上swagger-ui，可以有很好的呈現。

95150384

SpringBoot集成

這裡選用的swagger版本為：2.8.0

0.pom依賴

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

</dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

</dependency>

1. 編寫配置文件(Swagger2Config.java)

主要是添加註解@EnableSwagger2和定義Docket的bean類。

@EnableSwagger2

@Configuration

public class SwaggerConfig {

//是否開啟swagger，正式環境一般是需要關閉的，可根據springboot的多環境配置進行設置

@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.添加文檔內容(一般上是在Controller，請求參數上進行註解，這裡以上章節的UserController進行配置)

UserController

/**

* 用戶控制層簡單演示增刪改查及分頁

* 新增了swagger文檔內容 2018-07-21

* @author oKong

@RestController

@RequestMapping("/user")

@Api(tags="用戶API")

public class UserController {

@Autowired

IUserService userService;

@PostMapping("add")

@ApiOperation(value="用戶新增")

//正常業務時，需要在user類裡面進行事務控制，控制層一般不進行業務控制的。

//@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());

//由於設置了主鍵策略 id可不用賦值會自動生成

//user.setId(0L);

userService.insert(user);

Map<String,String> result = new HashMap<String,String>();

result.put("respCode", "01");

result.put("respMsg", "新增成功");

//事務測試

//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

調試：點擊需要訪問的api列表，點擊try it out!按鈕，即可彈出一下頁面：

16146099

執行：

92397999

結果：

64512351

大家可下載示例，查看自定義的字元出現的位置，這樣可以對其有個大致了解，各欄位的作用領域是哪裡。

Swagger常用屬性說明

Snipaste_2018-08-18_12-37-51

常用的註解@Api、@ApiOperation、@ApiModel、@ApiModelProperty示例中有進行標註，對於其他註解，大家可自動谷歌，畢竟常用的就這幾個了。有了swagger之後，原本一些post請求需要postman這樣的調試工具來進行發起，而現在直接在頁面上就可以進行調試了，是不是很爽！對於服務的調用者而已，有了這份api文檔也是一目了然，不需要和後端多少溝通成本，按著api說明進行前端開發即可。

總結

本章節主要是對Swagger的集成和簡單使用進行了說明，詳細的用法，可自行搜索相關資料下，這裡就不闡述了。因為對於百分之八十之上的文檔要求基本能滿足了。一些比如前端根據swagger的api-docs進行前端的快速開發，這就需要實際情況實際約定了，比如快速的生成表單頁等也是很方便的事情。最後，強烈建議在生產環境關閉swagger,避免不必要的漏洞暴露！

最後

目前互聯網上很多大佬都有SpringBoot系列教程，如有雷同，請多多包涵了。本文是作者在電腦前一字一句敲的，每一步都是實踐的。若文中有所錯誤之處，還望提出，謝謝。

系列