集成swagger
swagger名气很大,用来生成接口 文档的,相信大家都知道。不过swagger界面不够美观,使用起来不太方便,我这次安利的是一款国人开发的基于swagger二次开发的库-knife4j,用过的都说好!
第一步,引入依赖
<!-- swagger -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>${knife4j.version}</version>
</dependency>
第二步,写配置类,其中basePackage里面的包名要改成你自己controller的包名,swagger会在这个包名扫描注解生成文档
@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {
@Bean
public Docket adminApi() {
List<ResponseMessage> responseMessageList = new ArrayList();
responseMessageList.add((new ResponseMessageBuilder()).code(200).message("请求成功").build());
return new Docket(DocumentationType.SWAGGER_2)
.directModelSubstitute(LocalDateTime.class, Date.class)
.directModelSubstitute(LocalDate.class, Date.class)
.directModelSubstitute(LocalTime.class, Date.class)
.groupName("后台接口")
.globalResponseMessage(RequestMethod.GET, responseMessageList)
.globalResponseMessage(RequestMethod.POST, responseMessageList)
.globalResponseMessage(RequestMethod.PUT, responseMessageList)
.globalResponseMessage(RequestMethod.DELETE, responseMessageList)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.wkt.controller"))
.build()
.securitySchemes(securitySchemes())
.securityContexts(securityContexts());
}
第三步,打开浏览器,输入服务器地址/doc.html能正常打开说明成功了
集成统一返回值
对于接口返回的格式,应该统一,这样对于前端对接会便利许多
首先定义一个返回类,其中@ApiModelProperty是swagger注解,用在bean或者实体类的属性上,这样返回的接口文档中就能看到属性的说明了
@Data
@Accessors(chain = true)
public class Result<T> {
public final static int FAIL = 0;
public final static int OK = 200;
public final static int BAD_REQUEST = 400;
public final static int UNAUTHORIZED = 401;
public final static int FORBIDDEN = 403;
@ApiModelProperty(value = "状态码,200表示成功, 401表示未登录, 403表示无权限", position = 0)
private int status;
@ApiModelProperty(value = "成功或错误消息", position = 1)
private String message;
@ApiModelProperty(value = "返回数据", position = 2)
private T data;
@Override
public String toString() {
return "Result{" +
"status=" + status +
", message='" + message + '\'' +
'}';
}
}
定义一个BaseController,所有controller继承这个BaseController
public class BaseController {
public Result resultOk() {
return ResultUtils.resultOk();
}
public <T extends Result> T resultOk(Object data) {
return ResultUtils.resultOk(data);
}
public <T extends Result> T resultOk(Object data, String msg) {
return ResultUtils.resultOk(data, msg);
}
public Result resultFail() {
return ResultUtils.resultFail();
}
public Result resultFail(String msg) {
return ResultUtils.resultFail(msg);
}
public Result resultFail(int code, String msg) {
return ResultUtils.resultFail(code, msg);
}
}
编写一个测试controller试试,其实@Api注解用来指定swagger文档的分组名,@ApiOperation指定接口说明
@RestController
@RequestMapping("/user")
@Api(tags = "用户管理")
public class UserController extends BaseController {
@ApiOperation(value = "用户详情")
@GetMapping("{id}")
public Result<User> detail(@PathVariable int id) {
User user = new User();
user.setRealName("wali");
user.setPassword("123");
return resultOk(user);
}
}
调试下试试,可以看到knife4j会在返回的字段后面映射上说明,对前端的小伙伴相当友好,同时我们看到左边有个Authorize菜单可以配置token,这样就不用每次填写了,相当方便