001 Swagger2的使用

一、添加依赖

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

二、添加配置且Swapper分组

package com.epf.supply.config;

import java.util.ArrayList;
import java.util.List;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.context.request.async.DeferredResult;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@Configuration
@EnableSwagger2
public class SwaggerConfig {

	@Bean
    public Docket userApi() {
		
		ParameterBuilder tokenPar = new ParameterBuilder();
    	List<Parameter> pars = new ArrayList<Parameter>();
    	//全局需要token
    	tokenPar.name("token").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
    	pars.add(tokenPar.build());

        Docket docket = new Docket(DocumentationType.SWAGGER_2)
        		.groupName("Api")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.epf.supply"))//过滤的接口
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars);
        return docket;
    }
	
	
	@Bean
    public Docket innerApi() {
    	
		ParameterBuilder tokenPar = new ParameterBuilder();
    	List<Parameter> pars = new ArrayList<Parameter>();
    	//全局需要token
    	tokenPar.name("token").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
    	pars.add(tokenPar.build());

        Docket docket = new Docket(DocumentationType.SWAGGER_2)
        		.groupName("InnerApi")
                .apiInfo(innerApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.epf.supply"))//过滤的接口
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars);
        return docket;
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("深圳壹平台部委二级市场供需接口平台")
        		.description("供需平台相关数据接口")
                .termsOfServiceUrl("http://www.epf.cn/")
                .contact("二级市场项目组")
                .license("Licence Version 1.0").licenseUrl("#").version("1.0").build();
    }
	
    
    private ApiInfo innerApiInfo() {
    	  return new ApiInfoBuilder().title("深圳壹平台部委二级市场供需接口平台-内部")
          		.description("供需平台相关数据接口-内部")
                  .termsOfServiceUrl("http://www.epf.cn/")
                  .contact("二级市场项目组")
                  .license("Licence Version 1.0").licenseUrl("#").version("1.0").build();
    }
}

三、Swagger常用注解

1.@Api

@RestController
@RequestMapping("tapproval")
@Api(value = "供需平台供给审批表",tags="供需平台供给审批表")
public class TApprovalController extends BaseController{
    ...
}

2.@ApiOperation注解用于放在方法上面，其中value是该类的简短的叙述，notes一般是该方法的详细描述。

@ApiOperation(value="获取TApprovalJSON", notes="获取供需出让种类的数据列表")
@ApiImplicitParams({
	@ApiImplicitParam(name="pageSize",value="页面大小",dataType="Integer",paramType="query",required=true),
	@ApiImplicitParam(name="pageNo",value="第几页",  dataType="Integer",paramType="query",required=true),
	@ApiImplicitParam(name="conditons",value="查询条件",dataType="String",paramType="query",required=true)
})
@GetMapping("/getTApprovalJson")
@ResponseBody
public R getTApprovalJson(JqGridSearchTo jqGridSearchTo,HttpServletRequest request) throws NoSuchFieldException, SecurityException{
    ...
}

3.@ApiImplicitParam 与 @ApiImplicitParams

• @ApiImplicitParam注解用于表明前端传入的name参数的名字，required是否为必需项，以及dataType参数类型，以及paramType传递方式（query表示使用url问号的方式传参，这种比较常用，如果使用formData的方式进行传参，那么paramType的值为 form）.
• 当有多个参数时，需要用@ApiImplicitParams将@ApiImplicitParam包起来

@ApiOperation(value="获取TApprovalJSON", notes="获取供需出让种类的数据列表")
@ApiImplicitParams({
	@ApiImplicitParam(name="pageSize",value="页面大小",dataType="Integer",paramType="query",required=true),
	@ApiImplicitParam(name="pageNo",value="第几页",  dataType="Integer",paramType="query",required=true),
	@ApiImplicitParam(name="conditons",value="查询条件",dataType="String",paramType="query",required=true)
})
@GetMapping("/getTApprovalJson")
@ResponseBody
public R getTApprovalJson(JqGridSearchTo jqGridSearchTo,HttpServletRequest request) throws NoSuchFieldException, SecurityException{
    ...
}

4.如果传递的是pojo类型的参数,这里的Data Type为 Model,此时我们可以在实体类的代码中添加注解，选择我们需要在这里显示的属性。

• @ApiModelProperty(hidden = true)表示不需要在swagger页面进行展示，required表示该属性为必需的属性。

@Table(name="T_APPROVAL")
@ApiModel(value="审批表",description="审批实体")
public class TApprovalEntity implements Serializable {

    //审批意见
    @ApiModelProperty(required=true, notes="审批意见",dataType="String",example="同意！")
    private String opinion;
    
}

5.如果上传的是媒体文件类型

• 不用写什么配置