swagger配置即使用-白红宇

swagger配置即使用

阅读量：6884 次

发布时间：2019-06-27

本文共 9184 字，大约阅读时间需要 30 分钟。

先展示一下效果图

配置流程：

1.添加依赖：


    		
    			
     
      io.springfox
     			
     
      springfox-swagger2
     			
     
      2.6.1
     		
    		
    			
     
      io.springfox
     			
     
      springfox-swagger-ui
     			
     
      2.6.1

2.swagger配置：

package com.ligowave.bill.common.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;@Configurationpublic class SwaggerConfig {    @Bean    public Docket createRestApi(){        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                .select()                // Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore注解的API）                .apis(RequestHandlerSelectors.basePackage("com.ligowave.bill.web"))                // 可以根据url路径设置哪些请求加入文档，忽略哪些请求                .paths(PathSelectors.any())                .build();    }    private ApiInfo apiInfo(){        return new ApiInfoBuilder()                // 页面标题                .title("billing api")                // 描述                .description("计费系统API接口服务文档")                .build();    }}

3.启动类上添加@EnableSwagger2表示开启swagger注解

package com.ligowave;import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;import springfox.documentation.swagger2.annotations.EnableSwagger2;@SpringBootApplication@EnableSwagger2public class ApiServiceBillingApplication {	public static void main(String[] args) {		SpringApplication.run(ApiServiceBillingApplication.class, args);	}}

4、restful接口：

package com.ligowave.bill.web;import com.ligowave.bill.common.bean.Response;import com.ligowave.bill.common.bean.ResponseCode;import com.ligowave.bill.common.bean.ResponseMsg;import com.ligowave.bill.common.bean.User;import com.ligowave.bill.domain.billsystem.entity.BasePackage;import com.ligowave.bill.domain.billsystem.vo.BasePackageEdit;import com.ligowave.bill.domain.billsystem.vo.BasePackageQuery;import com.ligowave.bill.domain.billsystem.vo.BasePackageSave;import com.ligowave.bill.service.BasePackageService;import com.ligowave.bill.web.base.BaseController;import io.swagger.annotations.*;import org.apache.commons.lang3.StringUtils;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.data.domain.Page;import org.springframework.http.MediaType;import org.springframework.web.bind.annotation.*;import javax.servlet.http.HttpServletRequest;import java.util.List;@Api(value = "BasePackageController", tags = {"套餐操作接口"})@RestControllerpublic class BasePackageController extends BaseController {    @Autowired    BasePackageService basePackageService;    /**     * 获取套餐的分页列表     */    @ApiOperation(value = "高级搜索获取套餐的分页列表")    @ApiImplicitParam(name = "basePackageQuery", value = "套餐列表查询条件对象", required = true, dataType = "BasePackageQuery")    @RequestMapping(value = "/basepackage/basepackages", method = {RequestMethod.POST}, produces = MediaType.APPLICATION_JSON_VALUE)    public Page
    
      pageList(@RequestBody BasePackageQuery basePackageQuery) {        return basePackageService.findPageList(basePackageQuery);    }    /**     * 根据id获取套餐的详细信息     */    @ApiOperation(value = "根据id获取套餐的详细信息")    @ApiImplicitParam(name = "id", value = "套餐ID", required = true, dataType = "Integer",paramType = "path")    @RequestMapping(value = "/basepackage/{id}", method = RequestMethod.GET)    public Response
     
       getById(@PathVariable(value = "id") Integer id) {        BasePackage basePackage = basePackageService.getById(id);        if (null != basePackage) {            return new Response<>(ResponseCode.SUCCESS, ResponseMsg.SUCCESS, basePackage);        } else {            return new Response<>(ResponseCode.UNKNOWN_ERROR, ResponseMsg.UNKNOWN_ERROR, null);        }    }    /**     * 修改套餐     */    @ApiOperation(value = "更新套餐信息",notes="根据url的id来指定更新对象，并根据传过来的basePackageEdit信息来更新套餐详细信息")    @ApiImplicitParams({            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long",paramType = "path"),            @ApiImplicitParam(name = "basePackageEdit", value = "套餐详细实体", required = true, dataType = "BasePackageEdit")    })    @RequestMapping(value = "/basepackage/{id}", method = RequestMethod.PUT)    public Response
      
        update(@PathVariable(value = "id") Integer id,                                        @RequestBody BasePackageEdit basePackageEdit) {        BasePackage basePackage = basePackageService.update(id, basePackageEdit);        return new Response<>(ResponseCode.SUCCESS, ResponseMsg.SUCCESS, basePackage);    }    /**     * 根据id删除套餐     */    @ApiOperation(value = "删除套餐",notes="根据url的id来指定删除对象")    @ApiImplicitParam(name = "id", value = "套餐ID", required = true, dataType = "Integer",paramType = "path")    @RequestMapping(value = "/basepackage/{id}", method = RequestMethod.DELETE)    public Response
       
         deleteById(@PathVariable(value = "id") Integer id) {        try {            basePackageService.deleteByID(id);        } catch (Exception e) {            e.printStackTrace();            return new Response<>(ResponseCode.UNKNOWN_ERROR, ResponseMsg.UNKNOWN_ERROR, null);        }        return new Response<>(ResponseCode.SUCCESS, ResponseMsg.SUCCESS, null);    }    /**     * 添加套餐     */    @ApiOperation(value = "添加套餐")    @ApiImplicitParam(name = "basePackageSave", value = "套餐详细实体", required = true,dataType = "BasePackageSave")    @RequestMapping(value = "/basepackage", method = RequestMethod.POST)    public Response
        
          save(@RequestBody  BasePackageSave basePackageSave, HttpServletRequest request) {        User user = getCurrentEmployee(request);        //校验套餐名称、下架时间、最大出账周期、套餐价格不能为空        if (StringUtils.isBlank(basePackageSave.getName()) || StringUtils.isBlank(basePackageSave.getEndTimeStr()) || basePackageSave.getMaximumAccount() == null ||                basePackageSave.getPackagePrice() == null) {            return new Response<>(ResponseCode.PACKAGE_PARAM_ERROR, ResponseMsg.PACKAGE_PARAM_ERROR, null);        }        //校验套餐名称是否存在        if (checkNameExist(basePackageSave.getName(), user.getOrgid())) {            return new Response<>(ResponseCode.PACKAGE_EXISTED, ResponseMsg.PACKAGE_EXISTED, null);        }        basePackageService.save(basePackageSave);        return new Response<>(ResponseCode.SUCCESS, ResponseMsg.SUCCESS, null);    }    /**     * 根据套餐名和组织ID验证唯一性     */    private boolean checkNameExist(String name, String orgId) {        boolean exist = false;        if (!StringUtils.isBlank(name)) {            List
         
           list = basePackageService.findByNameAndOrgId(name, orgId); if (null != list && list.size() > 0) { exist = true; } } return exist; }}

上述用到的swagger注解有：

@Api()用于类

@ApiOperation()用于方法

@ApiParam()用于方法，参数，字段说明

5.用于接收传入参数的对象：

package com.ligowave.bill.domain.billsystem.vo;import io.swagger.annotations.ApiModel;import io.swagger.annotations.ApiModelProperty;/** * 套餐列表搜索条件 */@ApiModel(description = "套餐列表查询条件")public class BasePackageQuery extends BaseQuery {    @ApiModelProperty(value = "套餐名称", dataType = "String")    private String name;    @ApiModelProperty(value = "描述", dataType = "String")    private String description;    @ApiModelProperty(value = "是否被引用", dataType = "Integer", notes = "0-是,1-否")    private Integer whetherReferenced;    @ApiModelProperty(value = "发布时间始于", dataType = "String", notes = "格式为：yyyy-MM-dd HH:mm:ss")    private String beforeBegintime;    @ApiModelProperty(value = "发布时间终于", dataType = "String", notes = "格式为：yyyy-MM-dd HH:mm:ss")    private String afterBegintime;    @ApiModelProperty(value = "组织ID", dataType = "String")    private String orgId;    public String getName() {        return name;    }    public void setName(String name) {        this.name = name;    }    public String getDescription() {        return description;    }    public void setDescription(String description) {        this.description = description;    }    public String getBeforeBegintime() {        return beforeBegintime;    }    public void setBeforeBegintime(String beforeBegintime) {        this.beforeBegintime = beforeBegintime;    }    public String getAfterBegintime() {        return afterBegintime;    }    public void setAfterBegintime(String afterBegintime) {        this.afterBegintime = afterBegintime;    }    public Integer getWhetherReferenced() {        return whetherReferenced;    }    public void setWhetherReferenced(int whetherReferenced) {        this.whetherReferenced = whetherReferenced;    }    public String getOrgId() {        return orgId;    }    public void setOrgId(String orgId) {        this.orgId = orgId;    }}

效果图展示：