001 Swagger2的使用

素颜马尾好姑娘i 2022-03-06 11:18 183阅读 0赞

#### 一、添加依赖 ####

<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包起来

#### 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.如果上传的是媒体文件类型 ####

*  不用写什么配置