swagger学习日记1 swagger测试接口时传入参数的类型问题

蔚落 2022-11-21 01:04 172阅读 0赞

# 问题现象: #

今天在学习swagger做接口api说明的时候,出现了一个一直解决不了的问题,而且网上搜了很久,都找不到任何相似的问题和解决方法:

当用swagger测试一个需要传入(**Integer数据类型**)参数的接口时,一直是显示**红框状态**,不能被**execute(执行)**,没有任何错误提示!

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MjU4NTM4Ng_size_16_color_FFFFFF_t_70][]

--------------------

# 问题分析: #

于是我就通过以下几个方面去查看问题所在:

**1.swagger依赖:(没问题)**

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

**2.swagger配置类(没问题):**

import org.springframework.beans.factory.annotation.Value;
    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.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @Configuration
    @EnableSwagger2//注解开启 swagger2 功能
    public class Swagger2Config {
    
    	//是否开启swagger，正式环境一般是需要关闭的
    	@Value("${swagger.enabled}")
    	private boolean enableSwagger;
    
    	@Bean
    	public Docket createRestApi() {
    		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()) //信息会在页面上展示
    				.enable(enableSwagger)//是否开启 (true 开启  false隐藏。生产环境建议隐藏)
    				.select().apis(RequestHandlerSelectors.basePackage("com.stephen.shopproduct.controller"))//扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
    				.paths(PathSelectors.any())//指定路径处理PathSelectors.any()代表所有的路径
    				.build();
    	}
    
    	private ApiInfo apiInfo() {
    		return new ApiInfoBuilder().title("Product使用Swagger2构建RESTful接口")
    				//设置文档标题(API名称)
    				.description("接口说明")//文档描述
    				.termsOfServiceUrl("http://127.0.0.1:8081/")//服务条款URL
    				// 注意URL要和配置文件中的端口号一致,否则会访问不了http://127.0.0.1:8091/swagger-ui.html
    				.contact(new Contact("stephen", "http://127.0.0.1:8081/", "thpower@sgy.com"))//联系信息
    				.version("1.0.0")//版本号
    				.description("API 内容描述").build();
    	}
    }

**3.Controller控制层**

import com.alibaba.fastjson.JSON;
    import com.stephen.shopproduct.service.ProductService;
    import com.stephen.shopcommon.model.Product;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiOperation;
    import lombok.extern.slf4j.Slf4j;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.PathVariable;
    import org.springframework.web.bind.annotation.RestController;
    
    @RestController
    @Slf4j
    @Api(value = "商品接口功能", tags = "ProductController", description = "商品接口相关介绍")
    public class ProductController {
    	@Autowired
    	private ProductService productService;
    
    	@ApiOperation(value = "根据商品pid查询商品信息", notes = "商品信息pid")
    	@ApiImplicitParam(name = "pid", value = "商品id", required = true, dataType = "Integer", paramType = "path")
    	@GetMapping("/product/{pid}")
    	public Product product(@PathVariable("pid") Integer pid) {
    		Product product = productService.findByPid(pid);
    		log.info("查询到商品:" + JSON.toJSONString(product));
    		return product;
    	}
    }

仔细检查发现都没有问题啊!我一开始猜测可能是swagger版本的问题,于是我试着再建一个接口先测试一下:

@ApiOperation(value = "根据商品id查询商品信息", notes = "商品信息id")
    	@ApiImplicitParam(name = "id", value = "商品id", required = true, dataType = "String", paramType = "path")
    	@GetMapping("/prod/{id}")
    	public Product product(@PathVariable("id") String id) {
    		Product product = new Product();
    		product.setPid(3);
    		product.setPname("好东西");
    		product.setPprice(10.0);
    		product.setStock(1000);
    		return product;
    	}

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MjU4NTM4Ng_size_16_color_FFFFFF_t_70 1][]

接口测试成功!这说明依赖包和配置类都没有问题,那么就只能是这个控制层出问题了,我想到两个方向:

**1.接口上的swagger注解属性配置有问题.**

**2.swaggerUI页面传入参数的格式有问题.**

通过网上查询的资料我发现:测试接口传入参数的时候基本上都是**直接输入值**即可,因此排除了 **"2.swaggerUI页面传入参数的格式有问题."** 这个原因.

那就只剩下第一个原因了:**swagger注解属性配置有问题;** 于是我又看了一遍接口的注解配置**: @ApiOperation** 和 **@ApiImplicitParam**

@ApiOperation(value = "根据商品pid查询商品信息", notes = "商品信息pid")
    	@ApiImplicitParam(name = "pid", value = "商品id", required = true, dataType = "Integer", paramType = "path")
    	@GetMapping("/product/{pid}")
    	public Product product(@PathVariable("pid") Integer pid) {
    		Product product = productService.findByPid(pid);
    		log.info("查询到商品:" + JSON.toJSONString(product));
    		return product;
    	}
    
    	@ApiOperation(value = "根据商品id查询商品信息", notes = "商品信息id")
    	@ApiImplicitParam(name = "id", value = "商品id", required = true, dataType = "String", paramType = "path")
    	@GetMapping("/prod/{id}")
    	public Product product(@PathVariable("id") String id) {
    		Product product = new Product();
    		product.setPid(3);
    		product.setPname("好东西");
    		product.setPprice(10.0);
    		product.setStock(1000);
    		return product;
    	}

看了半天也没看出有什么问题:**上面的接口测试时传入参数失败,而下面的接口却能成功!**

这两个接口唯一的有效区别就是**参数的类型了!**但是查看了一下**两个接口的dataType和接口参数的数据类型是一样的!**

尽管我知道一定是参数配置出了问题,但就是不知道问题在哪里!就在我百思不得其解,网上又找不到答案的情况下,

我想着如果不指定参数类型会怎么样呢?于是把dataType属性去掉,发现成功了:

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MjU4NTM4Ng_size_16_color_FFFFFF_t_70 2][]

但是有一个细节,可能很多人没有注意到,**接口的参数类型显示是错的(并不是Integer)**:

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MjU4NTM4Ng_size_16_color_FFFFFF_t_70 3][]

这里显示的是string类型,这说明当不指定dataType的时候,默认是传入String类型的参数,

**但不知道为什么会自动检测并匹配了接口参数类型?**得看看源码才知道了!

**这个问题要是有知情的小伙伴请一定在评论区留下你的精彩评论,感谢.**

后来突发奇想: 如果**参数类型是Integer,那对应的dataType有没有可能是int?**

结果真的如我所料,修改之后接口测试**成功**了(神奇):

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MjU4NTM4Ng_size_16_color_FFFFFF_t_70 4][]

而且接口的参数类型显示是对的**(integer)**:

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MjU4NTM4Ng_size_16_color_FFFFFF_t_70 5][]

虽然解决了问题,但我还是建议swagger官方可以解决这个bug,让dataType和参数类型对应起来,Integer就应该对应Integer,int对应int,毕竟学过java的都知道这两者不是同一类型的,不然很容易混淆!!!!!!

--------------------

# 解决方法: #

将**@ApiImplicitParam **中 **dataType** 的值 **Integer** 修改为 **int:**

@ApiOperation(value = "根据商品pid查询商品信息", notes = "商品信息pid")
    	@ApiImplicitParam(name = "pid", value = "商品id", required = true, dataType = "int", paramType = "path")
    	@GetMapping("/product/{pid}")
    	public Product product(@PathVariable("pid") Integer pid) {
    		Product product = productService.findByPid(pid);
    		log.info("查询到商品:" + JSON.toJSONString(product));
    		return product;
    	}

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MjU4NTM4Ng_size_16_color_FFFFFF_t_70]: /images/20221120/643b0970ce2346ae9cb436257fbe40f2.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MjU4NTM4Ng_size_16_color_FFFFFF_t_70 1]: /images/20221120/f103ba71962f4feb9fe9a0ebcf0198e9.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MjU4NTM4Ng_size_16_color_FFFFFF_t_70 2]: /images/20221120/482ed87dc48b4d2a8398c10b212ac137.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MjU4NTM4Ng_size_16_color_FFFFFF_t_70 3]: /images/20221120/79d47a2e4dd844c093bf4571dce40fcd.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MjU4NTM4Ng_size_16_color_FFFFFF_t_70 4]: https://img-blog.csdnimg.cn/20201029101627400.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MjU4NTM4Ng==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MjU4NTM4Ng_size_16_color_FFFFFF_t_70 5]: https://img-blog.csdnimg.cn/20201029180332370.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MjU4NTM4Ng==,size_16,color_FFFFFF,t_70