springboot整合swagger2簡單例項
阿新 • • 發佈：2019-02-17
相信各位在公司寫API文件數量應該不少，當然如果你還處在自己一個人開發前後臺的年代，當我沒說，如今為了前後臺更好的對接，還是為了以後交接方便，都有要求寫API文件。
手寫Api文件的幾個痛點：
- 文件需要更新的時候，需要再次傳送一份給前端，也就是文件更新交流不及時。
- 介面返回結果不明確
- 不能直接線上測試介面，通常需要使用工具，比如postman
- 介面文件太多，不好管理
Swagger也就是為了解決這個問題，當然也不能說Swagger就一定是完美的，當然也有缺點，最明顯的就是程式碼移入性比較強。
其他的不多說，想要了解Swagger的，可以去Swagger官網，可以直接使用Swagger editor編寫介面文件，當然我們這裡講解的是SpringBoot整合Swagger2，直接生成介面文件的方式。
一、依賴
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId> 二、Swagger配置類
其實這個配置類，只要瞭解具體能配置哪些東西就好了，畢竟這個東西配置一次之後就不用再動了。 特別要注意的是裡面配置了api檔案也就是controller包的路徑，不然生成的文件掃描不到介面。
package cn.saytime;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import 用@Configuration註解該類，等價於XML中配置beans；用@Bean標註方法等價於XML中配置bean。
Application.class 加上註解@EnableSwagger2 表示開啟Swagger
package cn.saytime;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@SpringBootApplication
@EnableSwagger2
public class SpringbootSwagger2Application {
public static void main(String[] args) {
SpringApplication.run(SpringbootSwagger2Application.class, args);
}
}三、Restful 介面
package cn.saytime.web;
import cn.saytime.bean.JsonResult;
import cn.saytime.bean.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
/**
* @author zh
* @ClassName cn.saytime.web.UserController
* @Description
*/
@RestController
public class UserController {
// 建立執行緒安全的Map
static Map<Integer, User> users = Collections.synchronizedMap(new HashMap<Integer, User>());
/**
* 根據ID查詢使用者
* @param id
* @return
*/
@ApiOperation(value="獲取使用者詳細資訊", notes="根據url的id來獲取使用者詳細資訊")
@ApiImplicitParam(name = "id", value = "使用者ID", required = true, dataType = "Integer", paramType = "path")
@RequestMapping(value = "user/{id}", method = RequestMethod.GET)
public ResponseEntity<JsonResult> getUserById (@PathVariable(value = "id") Integer id){
JsonResult r = new JsonResult();
try {
User user = users.get(id);
r.setResult(user);
r.setStatus("ok");
} catch (Exception e) {
r.setResult(e.getClass().getName() + ":" + e.getMessage());
r.setStatus("error");
e.printStackTrace();
}
return ResponseEntity.ok(r);
}
/**
* 查詢使用者列表
* @return
*/
@ApiOperation(value="獲取使用者列表", notes="獲取使用者列表")
@RequestMapping(value = "users", method = RequestMethod.GET)
public ResponseEntity<JsonResult> getUserList (){
JsonResult r = new JsonResult();
try {
List<User> userList = new ArrayList<User>(users.values());
r.setResult(userList);
r.setStatus("ok");
} catch (Exception e) {
r.setResult(e.getClass().getName() + ":" + e.getMessage());
r.setStatus("error");
e.printStackTrace();
}
return ResponseEntity.ok(r);
}
/**
* 新增使用者
* @param user
* @return
*/
@ApiOperation(value="建立使用者", notes="根據User物件建立使用者")
@ApiImplicitParam(name = "user", value = "使用者詳細實體user", required = true, dataType = "User")
@RequestMapping(value = "user", method = RequestMethod.POST)
public ResponseEntity<JsonResult> add (@RequestBody User user){
JsonResult r = new JsonResult();
try {
users.put(user.getId(), user);
r.setResult(user.getId());
r.setStatus("ok");
} catch (Exception e) {
r.setResult(e.getClass().getName() + ":" + e.getMessage());
r.setStatus("error");
e.printStackTrace();
}
return ResponseEntity.ok(r);
}
/**
* 根據id刪除使用者
* @param id
* @return
*/
@ApiOperation(value="刪除使用者", notes="根據url的id來指定刪除使用者")
@ApiImplicitParam(name = "id", value = "使用者ID", required = true, dataType = "Long", paramType = "path")
@RequestMapping(value = "user/{id}", method = RequestMethod.DELETE)
public ResponseEntity<JsonResult> delete (@PathVariable(value = "id") Integer id){
JsonResult r = new JsonResult();
try {
users.remove(id);
r.setResult(id);
r.setStatus("ok");
} catch (Exception e) {
r.setResult(e.getClass().getName() + ":" + e.getMessage());
r.setStatus("error");
e.printStackTrace();
}
return ResponseEntity.ok(r);
}
/**
* 根據id修改使用者資訊
* @param user
* @return
*/
@ApiOperation(value="更新資訊", notes="根據url的id來指定更新使用者資訊")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "使用者ID", required = true, dataType = "Long",paramType = "path"),
@ApiImplicitParam(name = "user", value = "使用者實體user", required = true, dataType = "User")
})
@RequestMapping(value = "user/{id}", method = RequestMethod.PUT)
public ResponseEntity<JsonResult> update (@PathVariable("id") Integer id, @RequestBody User user){
JsonResult r = new JsonResult();
try {
User u = users.get(id);
u.setUsername(user.getUsername());
u.setAge(user.getAge());
users.put(id, u);
r.setResult(u);
r.setStatus("ok");
} catch (Exception e) {
r.setResult(e.getClass().getName() + ":" + e.getMessage());
r.setStatus("error");
e.printStackTrace();
}
return ResponseEntity.ok(r);
}
@ApiIgnore//使用該註解忽略這個API
@RequestMapping(value = "/hi", method = RequestMethod.GET)
public String jsonTest() {
return " hi you!";
}
}Json格式輸出類 JsonResult.class
package cn.saytime.bean;
public class JsonResult {
private String status = null;
private Object result = null;
// Getter Setter
}實體User.class
package cn.saytime.bean;
import java.util.Date;
/**
* @author zh
* @ClassName cn.saytime.bean.User
* @Description
*/
public class User {
private int id;
private String username;
private int age;
private Date ctm;
// Getter Setter
}專案結構：
四、Swagger2文件
具體裡面的內容以及介面測試，應該一看就懂了。這裡就不一一截圖了。
五、Swagger註解
swagger通過註解表明該介面會生成文件，包括介面名、請求方法、引數、返回資訊的等等。
- @Api：修飾整個類，描述Controller的作用
- @ApiOperation：描述一個類的一個方法，或者說一個介面
- @ApiParam：單個引數描述
- @ApiModel：用物件來接收引數
- @ApiProperty：用物件接收引數時，描述物件的一個欄位
- @ApiResponse：HTTP響應其中1個描述
- @ApiResponses：HTTP響應整體描述
- @ApiIgnore：使用該註解忽略這個API
- @ApiError ：發生錯誤返回的資訊
- @ApiImplicitParam：一個請求引數
- @ApiImplicitParams：多個請求引數
補充常用引數、屬性
備註（各引數意義）：
作用範圍 API 使用位置 物件屬性 @ApiModelProperty 用在出入引數物件的欄位上 協議集描述 @Api 用於controller類上 協議描述 @ApiOperation 用在controller的方法上 Response集 @ApiResponses 用在controller的方法上 Response @ApiResponse 用在 @ApiResponses裡邊 非物件引數集 @ApiImplicitParams 用在controller的方法上 非物件引數描述 @ApiImplicitParam 用在@ApiImplicitParams的方法裡邊 描述返回物件的意義 @ApiModel 用在返回物件類上
@ApiImplicitParam引數：
屬性 取值 作用 paramType 查詢引數型別 path 以地址的形式提交資料 query 直接跟引數完成自動對映賦值 body 以流的形式提交 僅支援POST header 引數在request headers 裡邊提交 form 以form表單的形式提交 僅支援POST dataType 引數的資料型別 只作為標誌說明，並沒有實際驗證 Long String name 接收引數名 value 接收引數的意義描述 required 引數是否必填 true 必填 false 非必填 defaultValue 預設值