SpringBoot入门-集成Swagger,统一返回值

集成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,这样就不用每次填写了，相当方便

 参考项目: https://gitee.com/huatin/java-test