SpringBoot使用(5)--集成swagger2

首先引入maven坐标

其次,配置配置类

package com.zbl.springboot.config;

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;

/**
 * @Author zhaobaolong
 * @Date 2018/8/14 0014
 */

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zbl.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .description("2018.8.14")
               .termsOfServiceUrl("http://localhost:8080")
                .contact("测试")
                .version("1.0")
                .build();
    }

}

@EnableSwagger2是启用swagger的注解

如果你使用了shiro框架,那么需要加上这几个放行的路径,否则是无法访问到swagger的页面的,因为被拦截了

package com.zbl.controller;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.zbl.entity.Order;
import com.zbl.entity.Result;
import com.zbl.entity.User;
import com.zbl.service.UserService;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;

import java.util.HashMap;
import java.util.List;
import java.util.Map;

/**
 * @Author zhaobaolong
 * @Date 2018/8/13 0013
 */


@Controller
@Api(description = "UserController", value = "User")
public class UserController {

    @Autowired
    private UserService userService;


    @RequestMapping(value = "getUser", method = {RequestMethod.GET, RequestMethod.POST}, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    @ResponseBody
    @ApiOperation(value = "获取用户信息接口", notes = "获取用户信息")
    public Result<List<User>> getUser() {

        List<User> userList = userService.getUser();
        Map<String, Object> map = new HashMap<>();
        map.put("user", userList);
        Result<List<User>> userResult = new Result<>();
        userResult.setCode(200);
        userResult.setMsg("接收成功");
        userResult.setData(userList);
        return userResult;
    }


    @RequestMapping(value = "getOrderById", method = {RequestMethod.GET, RequestMethod.POST}, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    @ResponseBody
    @ApiOperation(value = "根据id获取订单接口", notes = "根据id获取订单")
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Integer", paramType = "query")
    })
    @ApiResponses({
            @ApiResponse(code = 200, message = "成功")
    })
    public List<Order> getOrderById(Integer id) throws JsonProcessingException {
        List<Order> orderList = userService.getOrderById(id);
        ObjectMapper objectMapper = new ObjectMapper();
        return orderList;
    }

    @RequestMapping(value = "/login", method = {RequestMethod.GET, RequestMethod.POST}, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    @ResponseBody
    @ApiOperation(value = "登陆接口", notes = "登陆")

    public String login() {
        return "<h1>请登陆!<h1>";
    }


}

这是我配置好的一个Controller

常用swagger注解api可以看,这里重要的是返回值的处理,swagger默认会对返回一个对象进行处理,不能对返回json字符串进行处理,这里我使用了一个封装类来保存要传递的对象(运用泛型可以接受各种类型,提高通用性)

package com.zbl.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

/**
 * @Author zhaobaolong
 * @Date 2018/8/15 0015
 */

@ApiModel("返回参数")
public class  Result<T> {

    private T data;
    @ApiModelProperty("返回状态码")
    private Integer code;
    @ApiModelProperty("返回信息")
    private String msg;

    public T getData() {
        return data;
    }

    public void setData(T data) {
        this.data = data;
    }

    public Integer getCode() {
        return code;
    }

    public void setCode(Integer code) {
        this.code = code;
    }

    public String getMsg() {
        return msg;
    }

    public void setMsg(String msg) {
        this.msg = msg;
    }
}

效果如图

可以读取到返回的Result中的List参数信息,如果你在对应泛型中的实体类上使用了@ApiModelProperty注解,可以对参数进行说明

我的实体类是这样的

package com.zbl.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value="用户实体",description = "user")
public class User {
    private Integer id;
    @ApiModelProperty(value="vip名字",name = "vipname")
    private String vipname;
    @ApiModelProperty(value="昵称",name = "nickName")
    private String nickname;

    private Integer sex;

    private String banknum;

    private String idcardno;

    private String phone;

    private Integer viplevel;

    private String vipaccountnum;

    private String vipemail;

    private Integer roletype;

    private String imgpath;

    private String salt;

    private String password;

    private String address;

    private Integer status;

    private String createdate;

    private Integer createuserid;

    private String openid;

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getVipname() {
        return vipname;
    }

    public void setVipname(String vipname) {
        this.vipname = vipname == null ? null : vipname.trim();
    }

    public String getNickname() {
        return nickname;
    }

    public void setNickname(String nickname) {
        this.nickname = nickname == null ? null : nickname.trim();
    }

    public Integer getSex() {
        return sex;
    }

    public void setSex(Integer sex) {
        this.sex = sex;
    }

    public String getBanknum() {
        return banknum;
    }

    public void setBanknum(String banknum) {
        this.banknum = banknum == null ? null : banknum.trim();
    }

    public String getIdcardno() {
        return idcardno;
    }

    public void setIdcardno(String idcardno) {
        this.idcardno = idcardno == null ? null : idcardno.trim();
    }

    public String getPhone() {
        return phone;
    }

    public void setPhone(String phone) {
        this.phone = phone == null ? null : phone.trim();
    }

    public Integer getViplevel() {
        return viplevel;
    }

    public void setViplevel(Integer viplevel) {
        this.viplevel = viplevel;
    }

    public String getVipaccountnum() {
        return vipaccountnum;
    }

    public void setVipaccountnum(String vipaccountnum) {
        this.vipaccountnum = vipaccountnum == null ? null : vipaccountnum.trim();
    }

    public String getVipemail() {
        return vipemail;
    }

    public void setVipemail(String vipemail) {
        this.vipemail = vipemail == null ? null : vipemail.trim();
    }

    public Integer getRoletype() {
        return roletype;
    }

    public void setRoletype(Integer roletype) {
        this.roletype = roletype;
    }

    public String getImgpath() {
        return imgpath;
    }

    public void setImgpath(String imgpath) {
        this.imgpath = imgpath == null ? null : imgpath.trim();
    }

    public String getSalt() {
        return salt;
    }

    public void setSalt(String salt) {
        this.salt = salt == null ? null : salt.trim();
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password == null ? null : password.trim();
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address == null ? null : address.trim();
    }

    public Integer getStatus() {
        return status;
    }

    public void setStatus(Integer status) {
        this.status = status;
    }

    public String getCreatedate() {
        return createdate;
    }

    public void setCreatedate(String createdate) {
        this.createdate = createdate == null ? null : createdate.trim();
    }

    public Integer getCreateuserid() {
        return createuserid;
    }

    public void setCreateuserid(Integer createuserid) {
        this.createuserid = createuserid;
    }

    public String getOpenid() {
        return openid;
    }

    public void setOpenid(String openid) {
        this.openid = openid == null ? null : openid.trim();
    }
}