SpringBoot+Swagger2配置

1. 引入jar包依赖

	io.springfox
	springfox-swagger2
	2.7.0


	io.springfox
	springfox-swagger-ui
	2.7.0

2. Swagger2配置

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;
 
@Configuration
@EnableSwagger2
public class Swagger2 {
	
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.siwei.insurance.productManage"))
                .paths(PathSelectors.any())
                .build();
    }
    
    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("寿险")
                //描述
                .description("接口文档")
                //创建人
                //.contact(new Contact("LinXiuNan", "", ""))
                //版本号
                .version("1.0")
                .build();
    }
 
 
}

将该配置文件放在和Application启动类同等目录下即可

3. 创建接口

import java.util.List;

import javax.validation.Valid;

import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import com.github.pagehelper.PageHelper;
import com.github.pagehelper.PageInfo;
import com.siwei.insurance.entity.InsuranceCompany;
import com.siwei.insurance.helper.CodeConstant;
import com.siwei.insurance.helper.PageConstant;
import com.siwei.insurance.helper.PageResponseBody;
import com.siwei.insurance.helper.ResponseBody;
import com.siwei.insurance.productManage.service.InsuranceCompanyService;
import com.siwei.insurance.until.BindingResultUtil;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;

/**
 * 保险公司Controller
 * @author linxiunan
 * @date 2018年7月25日
 */
@RestController
@RequestMapping("/insureCompany")
@Api(tags = "保险公司Controller")
public class InsuranceCompanyController {
	
	@Autowired
	private InsuranceCompanyService insuranceCompanyService;
	
	private static final String UNIQUE_EMPTY_ERROR = "保险公司编码不能为空";

	@ApiOperation(value = "添加一条保险公司信息", notes = "添加一条保险公司信息")
	@PostMapping("/insertInsureCompany")
	public ResponseBody insertInsureCompany(@Valid InsuranceCompany insuranceCompany, BindingResult bindingResult) {
		if (bindingResult.hasErrors()) {
			return new ResponseBody(CodeConstant.GENERAL_ERROR, BindingResultUtil.getBindingResultErrMsg(bindingResult));
		}
		insuranceCompanyService.insertInsureCompany(insuranceCompany);
		return new ResponseBody();
	}
	
	@ApiOperation(value = "更新保险公司信息", notes = "根据保险公司编号更新保险公司信息")
	@PostMapping("/updateInsureCompany")
	public ResponseBody updateInsureCompany(@Valid InsuranceCompany insuranceCompany, BindingResult bindingResult) {
		if (bindingResult.hasErrors()) {
			return new ResponseBody(CodeConstant.GENERAL_ERROR, BindingResultUtil.getBindingResultErrMsg(bindingResult));
		}
		insuranceCompanyService.updateByPrimaryKey(insuranceCompany);
		return new ResponseBody();
	}
	
	@ApiOperation(value = "根据保险公司编码查询保险公司信息", notes = "根据保险公司编码查询保险公司信息")
	@ApiImplicitParam(name = "insCompanyNo", value = "保险公司编码", required = true, dataType = "String", paramType = "query")
	@PostMapping("/findInsureCompanyByInsNo")
	public ResponseBody findInsureCompanyByInsNo(@RequestParam String insCompanyNo) {
		if (StringUtils.isBlank(insCompanyNo)) {
			return new ResponseBody(CodeConstant.GENERAL_ERROR, UNIQUE_EMPTY_ERROR);
		}
		return insuranceCompanyService.findInsureCompanyByInsNo(insCompanyNo);
	}
	
	@ApiOperation(value = "删除保险公司信息", notes = "根据保险公司编码删除保险公司信息")
	@ApiImplicitParam(name = "insCompanyNo", value = "保险公司编码", required = true, dataType = "String", paramType = "query")
	@PostMapping("/deleteInsureCompanyByInsNo")
	public ResponseBody deleteInsureCompanyByInsNo(@RequestParam String insCompanyNo) {
		if (StringUtils.isBlank(insCompanyNo)) {
			return new ResponseBody(CodeConstant.GENERAL_ERROR, UNIQUE_EMPTY_ERROR);
		}
		insuranceCompanyService.deleteInsureCompanyByInsNo(insCompanyNo);
		return new ResponseBody();
	}
	
	@ApiOperation(value = "查询保险公司信息", notes = "分页查询符合条件的保险公司信息")
	@ApiImplicitParam(name = "isPage", value = "是否分页码(1分页,2不分页)", required = true, dataType = "Long", paramType = "query")
	@PostMapping("/findInsureCompanies")
	public ResponseBody findInsureCompanies(@RequestParam(defaultValue = PageConstant.PAGE_NUMBER) Integer pageNumber, 
											@RequestParam(defaultValue = PageConstant.PAGE_SIZE) Integer pageSize,
											InsuranceCompany insuranceCompany,
											@RequestParam Integer isPage) {
		if(isPage == 1) {
			PageHelper.startPage(pageNumber, pageSize);
			List resultList = insuranceCompanyService.findInsureCompanies(insuranceCompany);
			PageInfo pageInfo = new PageInfo<>(resultList);
			PageResponseBody pageResponseBody = new PageResponseBody(pageInfo.getTotal(), resultList);
			return new ResponseBody(pageResponseBody);
		} else if(isPage == 2) {
			List resultList = insuranceCompanyService.findInsureCompanies(insuranceCompany);
			return new ResponseBody(resultList);
		} else {
			return new ResponseBody(CodeConstant.GENERAL_ERROR, "是否分页状态码传入错误");
		}
		
	}
	
	@ApiOperation(value = "根据上级公司编码查找保险公司基本信息", notes = "根据上级公司编码查找保险公司基本信息")
	@ApiImplicitParam(name = "topCompanyNo", value = "上级公司编码", required = true, dataType = "String", paramType = "query")
	@PostMapping("/findBasicMsgByTopCompanyNo")
	public ResponseBody findBasicMsgByTopCompanyNo(@RequestParam String topCompanyNo) {
		if (StringUtils.isBlank(topCompanyNo)) {
			return new ResponseBody(CodeConstant.GENERAL_ERROR, UNIQUE_EMPTY_ERROR);
		}
		return insuranceCompanyService.findBasicMsgByTopCompanyNo(topCompanyNo);
	}
	
	@ApiOperation(value = "查找所有总公司编码、公司名称", notes = "查找所有总公司编码、公司名称")
	@PostMapping("/findSupCompaniesBasicMsg")
	public ResponseBody findSupCompaniesBasicMsg() {
		return insuranceCompanyService.findSupCompaniesBasicMsg();
	}
	
	@ApiOperation(value = "启用保险公司", notes = "启用保险公司")
	@ApiImplicitParam(name = "insCompanyNo", value = "保险公司编码", required = true, dataType = "String", paramType = "query")
	@PostMapping("/updateAble")
	public ResponseBody updateAble(@RequestParam String insCompanyNo) {
		if(StringUtils.isBlank(insCompanyNo)) {
			return new ResponseBody(CodeConstant.GENERAL_ERROR, UNIQUE_EMPTY_ERROR);
		}
		insuranceCompanyService.updateAble(insCompanyNo);
		return new ResponseBody();
	}
	
	@ApiOperation(value = "禁用保险公司", notes = "禁用保险公司")
	@ApiImplicitParam(name = "insCompanyNo", value = "保险公司编码", required = true, dataType = "String", paramType = "query")
	@PostMapping("/updateDisable")
	public ResponseBody updateDisable(@RequestParam String insCompanyNo) {
		if(StringUtils.isBlank(insCompanyNo)) {
			return new ResponseBody(CodeConstant.GENERAL_ERROR, UNIQUE_EMPTY_ERROR);
		}
		insuranceCompanyService.updateDisable(insCompanyNo);
		return new ResponseBody();
	}
	
	@ApiOperation(value = "根据保险公司编码查询信息", notes = "根据保险公司编码查询信息(验证保险公司编号是否存在)")
	@ApiImplicitParam(name = "insCompanyNo", value = "保险公司编码", required = true, dataType = "String", paramType = "query")
	@PostMapping("/findByInsNo")
	public ResponseBody findByInsNo(@RequestParam String insCompanyNo) {
		if(StringUtils.isBlank(insCompanyNo)) {
			return new ResponseBody(CodeConstant.GENERAL_ERROR, UNIQUE_EMPTY_ERROR);
		}
		return insuranceCompanyService.findByInsNo(insCompanyNo);
	}
}

统一返回格式类

import com.siwei.insurance.enums.ExceptionResultEnum;

/**
 * 返回对象封装类
 * @author linxiunan
 * @date 2018年7月26日
 */
public class ResponseBody {
	
	// 状态码
	private Integer state;
	
	// 提示信息
	private String message;

	// 返回数据
	private Object data;

	public Integer getState() {
		return state;
	}

	public void setState(Integer state) {
		this.state = state;
	}

	public String getMessage() {
		return message;
	}

	public void setMessage(String message) {
		this.message = message;
	}

	public Object getData() {
		return data;
	}

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

	public ResponseBody(Integer state, String message) {
		super();
		this.state = state;
		this.message = message;
	}

	public ResponseBody() {
		this.state = ExceptionResultEnum.SUCCESS.getstate();
		this.message = ExceptionResultEnum.SUCCESS.getMessage();
	}

	public ResponseBody(Object data) {
		super();
		this.state = ExceptionResultEnum.SUCCESS.getstate();
		this.message = ExceptionResultEnum.SUCCESS.getMessage();
		this.data = data;
	}

	public ResponseBody(ExceptionResultEnum exResEnum) {
		super();
		this.message = exResEnum.getMessage();
		this.state = exResEnum.getstate();
	}

}

实体类

package com.siwei.insurance.entity;

import org.hibernate.validator.constraints.NotBlank;

import com.siwei.insurance.config.BaseBean;

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

/**
 * 保险公司实体类
 * @author linxiunan
 * @date 2018年7月25日
 */
@ApiModel
public class InsuranceCompany extends BaseBean {

	@ApiModelProperty(value = "保险公司编码", required = true)
	@NotBlank(message = "保险公司编码不能为空")
	private String insCompanyNo;

	@ApiModelProperty(value = "保险公司名称", required = true)
	@NotBlank(message = "保险公司名称不能为空")
	private String insCompanyName;

	@ApiModelProperty(value = "保险公司级别 (1支公司,2分公司,3总公司)", required = true)
	@NotBlank(message = "保险公司级别不能为空")
	private String rank;

	@ApiModelProperty(value = "保险公司简称", required = true)
	private String insCompanyAbbr;
	
	@ApiModelProperty(value = "保险公司职业编码", required = true)
	@NotBlank(message = "保险公司职业编码不能为空")
	private String companyCareerCode;

	@ApiModelProperty(value = "上级公司名称")
	private String superiorCompanyName;

	@ApiModelProperty(value = "上级公司编码")
	private String superiorCompanyNo;
	
	@ApiModelProperty(value = "总公司名称")
	//@NotBlank(message = "总公司名称不能为空")
	private String topCompanyName;
	
	@ApiModelProperty(value = "总公司编码")
	//@NotBlank(message = "总公司编码不能为空")
	private String topCompanyNo;
	
	@ApiModelProperty(value = "成立日期")
	//@NotBlank(message = "成立日期不能为空")
	private String createDate;
	
	@ApiModelProperty(value = "公司所在省", required = true)
	@NotBlank(message = "公司所在省不能为空")
	private String province;
	
	@ApiModelProperty(value = "公司所在市", required = true)
	@NotBlank(message = "公司所在市不能为空")
	private String city;
	
	@ApiModelProperty(value = "公司所在县", required = true)
	@NotBlank(message = "公司所在县不能为空")
	private String county;
	
	@ApiModelProperty(value = "公司类别", required = true)
	@NotBlank(message = "公司类别不能为空")
	private String companyType;
	
	@ApiModelProperty(value = "存折开户行")
	//@NotBlank(message = "存折开户行不能为空")
	private String bankName;
	
	@ApiModelProperty(value = "账户号")
	//@NotBlank(message = "账户号不能为空")
	private String accountNo;
	
	@ApiModelProperty(value = "联行号")
	//@NotBlank(message = "联行号不能为空")
	private String bankNo;
	
	@ApiModelProperty(value = "合作状态", required = true)
	@NotBlank(message = "合作状态不能为空")
	private String state;
	
	@ApiModelProperty(value = "保险公司地址")
	//@NotBlank(message = "保险公司地址不能为空")
	private String address;
	
	@ApiModelProperty(value = "联系人姓名")
	//@NotBlank(message = "联系人姓名不能为空")
	private String contacts;
	
	@ApiModelProperty(value = "联系人电话")
	//@NotBlank(message = "联系人电话不能为空")
	//@Pattern(regexp = "^[1][3,4,5,8][0-9]{9}$", message="联系人电话格式错误")
	private String phone;
	
	@ApiModelProperty(value = "备注")
	private String note;

	public void setInsCompanyNo(String insCompanyNo) {
		this.insCompanyNo = insCompanyNo;
	}

	public String getInsCompanyNo() {
		return insCompanyNo;
	}

	public void setInsCompanyName(String insCompanyName) {
		this.insCompanyName = insCompanyName;
	}

	public String getInsCompanyName() {
		return insCompanyName;
	}

	public void setRank(String rank) {
		this.rank = rank;
	}

	public String getRank() {
		return rank;
	}

	public void setInsCompanyAbbr(String insCompanyAbbr) {
		this.insCompanyAbbr = insCompanyAbbr;
	}

	public String getInsCompanyAbbr() {
		return insCompanyAbbr;
	}

	public void setSuperiorCompanyName(String superiorCompanyName) {
		this.superiorCompanyName = superiorCompanyName;
	}

	public String getSuperiorCompanyName() {
		return superiorCompanyName;
	}

	public void setSuperiorCompanyNo(String superiorCompanyNo) {
		this.superiorCompanyNo = superiorCompanyNo;
	}

	public String getSuperiorCompanyNo() {
		return superiorCompanyNo;
	}

	public void setTopCompanyName(String topCompanyName) {
		this.topCompanyName = topCompanyName;
	}

	public String getTopCompanyName() {
		return topCompanyName;
	}

	public void setCreateDate(String createDate) {
		this.createDate = createDate;
	}

	public String getCreateDate() {
		return createDate;
	}

	public void setProvince(String province) {
		this.province = province;
	}

	public String getProvince() {
		return province;
	}

	public void setCity(String city) {
		this.city = city;
	}

	public String getCity() {
		return city;
	}

	public void setCounty(String county) {
		this.county = county;
	}

	public String getCounty() {
		return county;
	}

	public void setCompanyType(String companyType) {
		this.companyType = companyType;
	}

	public String getCompanyType() {
		return companyType;
	}

	public void setBankName(String bankName) {
		this.bankName = bankName;
	}

	public String getBankName() {
		return bankName;
	}

	public void setAccountNo(String accountNo) {
		this.accountNo = accountNo;
	}

	public String getAccountNo() {
		return accountNo;
	}

	public String getBankNo() {
		return bankNo;
	}

	public void setBankNo(String bankNo) {
		this.bankNo = bankNo;
	}

	public void setState(String state) {
		this.state = state;
	}

	public String getState() {
		return state;
	}

	public void setAddress(String address) {
		this.address = address;
	}

	public String getAddress() {
		return address;
	}

	public void setPhone(String phone) {
		this.phone = phone;
	}

	public String getPhone() {
		return phone;
	}

	public String getContacts() {
		return contacts;
	}

	public void setContacts(String contacts) {
		this.contacts = contacts;
	}

	public String getNote() {
		return note;
	}

	public void setNote(String note) {
		this.note = note;
	}

	public String getCompanyCareerCode() {
		return companyCareerCode;
	}

	public void setCompanyCareerCode(String companyCareerCode) {
		this.companyCareerCode = companyCareerCode;
	}

	public String getTopCompanyNo() {
		return topCompanyNo;
	}

	public void setTopCompanyNo(String topCompanyNo) {
		this.topCompanyNo = topCompanyNo;
	}

}

4. 启用查看文档

启动项目之后，访问localhost:8080/swagger-ui.html

5. Swagger相关文档

可以查看此链接，个人感觉比较详细  https://blog.csdn.net/xupeng874395012/article/details/68946676

6. Swagger改版

由于swagger默认的模板是上下分布的，可能有很多人用着感觉很不舒服，在这，我使用了一款第三方的插件，是一般后台的左右式分布，用起来比较舒服

只需要在pom文件中加入如下依赖

    com.github.caspar-chen
    swagger-ui-layer
    0.0.6

然后启动项目之后访问 localhost:8080/docs.html  即可