swagger配置即使用

先展示一下效果图

配置流程：

1.添加依赖：

	<!-- Swagger -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.6.1</version>
		</dependency>

		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.6.1</version>
		</dependency>

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;

@Configuration
public 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
@EnableSwagger2
public 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 = {"套餐操作接口"})
@RestController
public 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<BasePackage> 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<BasePackage> 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<BasePackage> 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<BasePackage> 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<BasePackage> 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<BasePackage> 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;
    }
}

效果图展示：

上述用到的注解：

• @ApiModel：用对象来接收参数
• @ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改 

6.swagger默认访问地址为：http://localhost:8080/swagger-ui.html