springboot集成swagger2总结

写这篇博客的初衷是为了总结自己在学习中所遇到的问题，给予后来者以提示。

至于springBoot如何集成swagger2大家可以参考这篇文章，本博客只记录自己在学习的过程遇到的问题以及是如何解决的。

问题1：

       集成swagger2以后，在本地访问http://localhost:8080/swagger-ui.html时，页面并没有自动生成相应的接口。如下图：

经过排查发现，在swagger配置类中的apis()方法中指定controller包的路径不规范,如下图：

@Configuration
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //指定controller包的路径不规范cn/com/boco/bootmybatis/controller
                .apis(RequestHandlerSelectors.basePackage("cn/com/boco/bootmybatis/controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restfun风格，http://blog.csdn.net/saytime")
                .termsOfServiceUrl("http://blog.csdn.net/saytime")
                .version("1.0")
                .build();
    }
}

正确的写法如下：

@Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.com.boco.bootmybatis.controller"))
                .paths(PathSelectors.any())
                .build();
    }

问题2：

        测试接口自动生成后，通过测试接口访问后台controller中的接口，总是返回400，具体信息如下图：

后来发现出现这种状况的原因是@ApiImplicitParam注解中的paramType属性引起的。我把paramType属性指定为"path",在方法中却是用@RequestParam注解获取参数，正确的做法是使用@PathVariable接受参数。下面是关于paramType属性类型的详细介绍：

paramType属性指定参数放在哪个地方

header：请求参数放置于Request Header，使用@RequestHeader获取 query：请求参数放置于请求地址，使用@RequestParam获取 path：（用于restful接口）-->请求参数的获取：@PathVariable body：（不常用） form（不常用）

下面是swagger使用注解及其说明：

@Api：用在类上，说明该类的作用。

@ApiOperation：注解来给API增加方法说明。

@ApiImplicitParams : 用在方法上包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

    l   code：数字，例如400

    l   message：信息，例如"请求参数没填好"

    l   response：抛出异常的类   

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

    l   @ApiModelProperty：描述一个model的属性

注意：@ApiImplicitParam的参数说明：

paramType：指定参数放在哪个地方	header：请求参数放置于Request Header，使用@RequestHeader获取 query：请求参数放置于请求地址，使用@RequestParam获取 path：（用于restful接口）-->请求参数的获取：@PathVariable body：（不常用） form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传	true | false
value：说明参数的意思
defaultValue：参数的默认值

参考文章：https://my.oschina.net/dlam/blog/808315