SpringBoot 集成 Api接口文檔生成工具Swagger2
爲什麼使用Swagger？
隨着互聯網的發展,微服務逐漸流行起來,在微服務的設計下,微服務必將會有大量的接口,對於清楚的手動編寫描述接口文檔的話,必定是非常令人頭疼抓狂，所以就選擇使用Swagger來幫我們實現並解決這個問題。
Swagger的優點：
- 自動生成文檔：只需要一些註解，它就可以根據代碼自動生成API文檔，保證了文檔的時效性。
- 跨語言性，支持四十多種語言。
- Swagger UI呈現出來的是一份可交互的API文檔，我們可以直接在文檔頁面嘗試API的調用，簡化了準備複雜的調用參數的過程。
- 還可以將文檔規範導入相關的工具，這些工具將會爲我們自動地創建自動化測試。
實現：
步驟一：在pom.xml文件中添加Swagger的依賴
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
步驟二：配置Swagger
@Configuration //該類爲配置類
@EnableSwagger2 //開啓Swagger
public class SwaggerConfig {
@Bean
public Docket getRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.java.spb"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("基於Swagger構建的Rest API 接口文檔")
.description("使用Swagger構建的Rest API文檔既方便又快捷")
.contact(new Contact("一個有靈魂的程序員","https://blog.csdn.net/lz527657138","[email protected]"))//作者信息
.version("1.0")
.build();
}
}
步驟三：Controller類添加Swagger註解
/**
* 控制層
*/
@Api(tags = "用戶管理")
@RestController
public class UserInfoController {
//注入用戶服務層
@Autowired
private UserService userService;
/**
* 獲取用戶列表
*/
@GetMapping("/getUsers")
public List<User> getUsers(Map<String, Object> queryMap){
List<User> users = userService.getUsers(queryMap);
return users;
}
/**
* 新增用戶信息
*/
@ApiOperation("新增用戶信息")
@PostMapping("/insert")
public String insertUser(@RequestBody User user){
Long insert = userService.insert(user);
return insert>0?"新增成功"+insert:"新增失敗" + insert;
}
/**
* 根據用戶id查詢信息
* 傳參形式使用Restful
*/
@ApiOperation(value = "根據id獲取用戶詳細信息",notes = "使用Restful風格路徑傳參")
@GetMapping("/getUser/{id}")
public User getUserById(@PathVariable("id") Long id){
User userInfo = userService.getUserById(id);
return userInfo;
}
/**
* 根據id刪除用戶信息
*/
@ApiOperation(value = "根據id刪除用戶信息",notes = "使用Restful風格路徑傳參")
@DeleteMapping("/delete/{id}")
public String deleteById(@PathVariable("id") Long id){
boolean delete = userService.delete(id);
return delete==true?"刪除成功":"刪除失敗";
}
}
步驟四：實體類添加Swagger註解
@Data
@NoArgsConstructor //無參構造函數
@AllArgsConstructor//有參構造(全字段)
@Accessors(chain = true)//鏈式; 存取器。通過該註解可以控制getter和setter方法的形式。
@ApiModel(description = "用戶類")
public class User {
@ApiModelProperty(value = "id")
private Long id;//主鍵
@ApiModelProperty(value = "真實姓名",example = "妖怪作妖")
private String userName;//真實姓名
@ApiModelProperty(value = "登錄帳號",example = "lzlz10")
private String userAccount;//登錄帳號
@ApiModelProperty(value = "登錄密碼",example = "123123123")
private String userPassword;//登錄密碼
@ApiModelProperty(value = "創建時間")
private Date createTime;//創建時間
@ApiModelProperty(value = "修改時間")
private Date modifyTime;//修改時間
@ApiModelProperty(value = "手機號碼",example = "18763372970")
private String telNum;//手機號碼
@ApiModelProperty(value = "性別",example = "0女/1男")
private Integer gender;//性別;0:女;1:男
@ApiModelProperty(value = "生日",example = "1992-05-21")
private Date birthday;//生日
@ApiModelProperty(value = "郵箱",example = "[email protected]")
private String email;//郵箱
}
步驟五：測試看看效果 http://localhost/swagger-ui.html
如有疑問或問題，請批評指正。