現代化的研發組織架構中,一個研發團隊基本包括了產品組、後端組、前端組、APP端研發、測試組、UI組等,各個細分組織人員各司其職,共同完成產品的全週期工作。如何進行組織架構內的有效高效溝通就顯得尤其重要。其中,如何構建一份合理高效的接口文檔更顯重要。
接口文檔橫貫各個端的研發人員,但是由於接口衆多,細節不一,有時候理解起來並不是那麼容易,引起‘內戰’也在所難免, 並且維護也是一大難題。
類似RAP文檔管理系統,將接口文檔進行在線維護,方便了前端和APP端人員查看進行對接開發,但是還是存在以下幾點問題:
•文檔是接口提供方手動導入的,是靜態文檔,沒有提供接口測試功能;•維護的難度不小。
Swagger的出現可以完美解決以上傳統接口管理方式存在的痛點。本文介紹Spring Boot整合Swagger2的流程,連帶填坑。
使用流程如下:
1)引入相應的maven包:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
2)編寫Swagger2的配置類:
import io.swagger.annotations.Api;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* Desc: swagger2配置類
*/
@SuppressWarnings({"unused"})
@Configuration @EnableSwagger2
public class Swagger2Config {
@Bean("UserApis")
public Docket userApis() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("用戶模塊")
.select()
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
.paths(PathSelectors.regex("/user.*"))
.build()
.apiInfo(apiInfo())
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("XXXXX系統平臺接口文檔")
.description("提供子模塊1/子模塊2/子模塊3的文檔")
.termsOfServiceUrl("https://www.baidu.com")
.version("1.0")
.build();
}
}
如上可見: 通過註解@EnableSwagger2
開啓swagger2,apiInfo是接口文檔的基本說明信息,包括標題、描述、服務網址、聯繫人、版本等信息;
在Docket創建中,通過groupName進行分組,paths屬性進行過濾,apis屬性可以設置掃描包,或者通過註解的方式標識;
通過enable屬性,可以在application-{profile}.properties
文件中設置相應值,主要用於控制生產環境不生成接口文檔。
3)controller層類和方法添加相關注解
import com.trace.bind.ResultModel;
import com.trace.entity.po.Area;
import com.trace.entity.po.User;
import com.trace.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import javax.annotation.Resource;
import java.util.List;
/**
* Desc: 用戶管理controller
*/
@SuppressWarnings("unused")
@RestController
@RequestMapping("/user")
@Api(tags = "用戶管理")
public class UserController {
@Resource private UserService userService;
@GetMapping("/query/{id}")
@ApiOperation("通過ID查詢")
@ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "int", paramType = "path")
public ResultModel<User> findById(@PathVariable int id) {
User user = userService.findById(id);
return ResultModel.success("id查詢成功", user);
}
@PostMapping("/insert")
@ApiOperation("新增默認用戶")
public ResultModel<Integer> insert() {
User user = new User();
user.setUserName("zhangsan");
userService.save(user);
return ResultModel.success("新增用戶成功", user.getId());
}
@PutMapping("/update")
@ApiOperation("更新用戶信息")
public ResultModel<Integer> update(User user) {
int row = userService.update(user);
return ResultModel.success(row);
}
@DeleteMapping("/delete")
@ApiOperation("刪除單個用戶")
@ApiImplicitParam(value = "用戶ID", required = true)
public ResultModel<Integer> delete(int id) {
return ResultModel.success(userService.delete(id));
}
}
4)返回對象ResultModel
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Getter;
import lombok.Setter;
/**
* Desc: 接口返回結果對象
*/
@SuppressWarnings("unused")
@Getter @Setter @ApiModel(description = "返回結果")
public final class ResultModel<T> {
@ApiModelProperty("是否成功: true or false")
private boolean result;
@ApiModelProperty("描述性原因")
private String message;
@ApiModelProperty("業務數據")
private T data;
private ResultModel(boolean result, String message, T data) {
this.result = result;
this.message = message;
this.data = data;
}
public static<T> ResultModel<T> success(T data) {
return new ResultModel<>(true, "SUCCESS", data);
}
public static<T> ResultModel<T> success(String message, T data) {
return new ResultModel<>(true, message, data);
}
public static ResultModel failure() {
return new ResultModel<>(false, "FAILURE", null);
}
public static ResultModel failure(String message) {
return new ResultModel<>(false, message, null);
}
}
5)ApiModel屬性對象 -- User實體
import com.trace.mapper.base.NotPersistent;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.util.List;
/**
* Created by Trace on 2017-12-01.<br/>
* Desc: 用戶表tb_user
*/
@SuppressWarnings("unused")
@Data @NoArgsConstructor @AllArgsConstructor
@ApiModel
public class User {
@ApiModelProperty("用戶ID") private Integer id;
@ApiModelProperty("賬戶名") private String userName;
@ApiModelProperty("用戶暱稱") private String nickName;
@ApiModelProperty("真實姓名") private String realName;
@ApiModelProperty("身份證號碼") private String identityCard;
@ApiModelProperty("性別") private String gender;
@ApiModelProperty("出生日期") private LocalDate birth;
@ApiModelProperty("手機號碼") private String phone;
@ApiModelProperty("郵箱") private String email;
@ApiModelProperty("密碼") private String password;
@ApiModelProperty("用戶頭像地址") private String logo;
@ApiModelProperty("賬戶狀態 0:正常; 1:凍結; 2:註銷") private Byte status;
@ApiModelProperty("個性簽名") private String summary;
@ApiModelProperty("用戶所在區域碼") private String areaCode;
@ApiModelProperty("註冊時間") private LocalDateTime registerTime;
@ApiModelProperty("最近登錄時間") private LocalDateTime lastLoginTime;
@NotPersistent @ApiModelProperty(hidden = true)
private transient Area area; //用戶所在地區
@NotPersistent @ApiModelProperty(hidden = true)
private transient List<Role> roles; //用戶角色列表
}
簡單說下Swagger2幾個重要註解:
@Api:用在請求的類上,表示對類的說明
•tags "說明該類的作用,可以在UI界面上看到的註解"•value "該參數沒什麼意義,在UI界面上也看到,所以不需要配置"
@ApiOperation:用在請求的方法上,說明方法的用途、作用
•value="說明方法的用途、作用"•notes="方法的備註說明"
@ApiImplicitParams:用在請求的方法上,表示一組參數說明 @ApiImplicitParam:用在@ApiImplicitParams註解中,指定一個請求參數的各個方面
•value:參數的漢字說明、解釋
•required:參數是否必須傳
•paramType: 參數放在哪個地方
1.header --> 請求參數的獲取:@RequestHeader
2.query --> 請求參數的獲取:@RequestParam
3.path(用於restful接口)--> 請求參數的獲取:@PathVariable
4.body(不常用)
5.form(不常用)
•dataType:參數類型,默認String,其它值dataType="Integer"
•defaultValue:參數的默認值
@ApiResponses:用在請求的方法上,表示一組響應 @ApiResponse:用在@ApiResponses中,一般用於表達一個錯誤的響應信息
•code:數字,例如400
•message:信息,例如"請求參數沒填好"
•response:拋出異常的類
@ApiModel:主要有兩種用途:
•用於響應類上,表示一個返回響應數據的信息•入參實體:使用@RequestBody這樣的場景, 請求參數無法使用@ApiImplicitParam註解進行描述的時候
@ApiModelProperty:用在屬性上,描述響應類的屬性 最終呈現結果:
那麼,啓動應用後,會自動生成http://{root-path}/swagger-ui.html
頁面,訪問後,效果如下所示: