swagger 踩坑记录

导入依赖

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

        <!--如果不加，则当实体类非String属性没有默认值时,会出现NumberFormatException: For input string:""，
       这是因为springfox-swagger2(2.9.2)依赖于swagger-models(1.5.20)
       该版本的swagger只判断了null没有判断空字串符
       所以会将实体类中非String类型的属性默认赋值为空字符串;
       而1.5.21版本之后新增了空串判断,所以就不会有该问题了-->
        <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-models</artifactId>
        <version>1.5.21</version>
        </dependency>

编写配置文件

package com.fan.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

/**
 * @author およそ神
 * @version JDK 1.8
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
        //swagger有自己的bean实例——Docket
        //配置了swagger
        @Bean
        public Docket docket(){
            //假设这里有一个业务，我只希望在生产环境中使用swagger，其他环境不需要
            //第一步，配置多个环境，第二步：传一个环境参数（Environment），
            //第三步：获取当前环境（environment.acceptsProfiles(profiles)），第四步：判断环境，第五步，传到enable方法中即可
            //这里就不多测试了
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    //自定义组名（团队开发中的一组），如果有多个组，就是多个Docket，一个组对应一个Docket
                    .groupName("fan")
                    .enable(true)//是否开启swagger，如果为false，则swagger不能在浏览器中被访问
                    //测试题，
                    .select()
                    //配置指定需要扫描的包，除了basePackage还有其他的可以点出来看，例如any none...
                    .apis(RequestHandlerSelectors.basePackage("com.fan.controller"))
                    //.paths(PathSelectors.any())//此方法为过滤方法
                    .build();
        }

        public ApiInfo apiInfo(){

            Contact contact = new Contact("fan", "https://blog.csdn.net/Fanzongshen?type=blog", "1035358739@qq.com");

            return new ApiInfo(
                    "凡总神的SwaggerApi文档",
                    "只要心存梦想，再小的帆也能远航 !",
                    "v1.0",
                    "https://blog.csdn.net/Fanzongshen?type=blog",
                    contact,
                    "Apache 2.0",
                    "http://www.apache.org/licenses/LICENSE-2.0",
                    new ArrayList()
            );
        }
    }
}

如果继承了WebMvcConfigurationSupport会产生一个跨域安全问题

/**
    * 跨域请求安全性问题 swagger2 这是老版本，把劳资整安逸了，最后才想到有问题
    * @param registry
    */
   @Override
   public void addResourceHandlers(ResourceHandlerRegistry registry) {
      registry.addResourceHandler("/**").addResourceLocations(
              "classpath:/static/");
      registry.addResourceHandler("swagger-ui.html").addResourceLocations(
              "classpath:/META-INF/resources/");
      registry.addResourceHandler("/webjars/**").addResourceLocations(
              "classpath:/META-INF/resources/webjars/");
      super.addResourceHandlers(registry);
   }

/**
    * 跨域请求安全性问题 swagger2 新版包括(http://localhost/doc.html#/home)访问
    * @param registry
    */
	@Override
   public void addResourceHandlers(ResourceHandlerRegistry registry) {
      /**注意这个配置,如果配置swagger-bootstrap-ui的位置不对,也是出现404的一个原因*/
      registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
      registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
      registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
      registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
   }

访问地址：http://localhost:8080/swagger-ui.html
最终效果

常见的参数问题

paramType：参数放在哪个地方
header-->请求参数的获取：@RequestHeader
query-->请求参数的获取：@RequestParam
path（用于restful接口）-->请求参数的获取：@PathVariable
body（不常用）
form（不常用）

对象写法

/**
     * 请求头携带token，保存单个person数据
     * @param person
     * @param token
     * @return
     */
    @ApiOperation(value = "请求头携带token，保存单个person数据")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "编号", dataType = "int" ,paramType = "query"),
            @ApiImplicitParam(name = "name", value = "名字", dataType = "string",paramType = "query" ,required = true),
            @ApiImplicitParam(name = "age", value = "年龄", dataType = "int",paramType = "query"),
            @ApiImplicitParam(name = "updateby", value = "修改人", dataType = "string",paramType = "query"),
            @ApiImplicitParam(name = "updatetime", value = "修改时间", dataType = "date",paramType = "query")
    })
    @PostMapping("/saveWithToken")
    public ResponseVO saveWithToken(@Validated  @ApiIgnore  Person person, @Validated @ApiParam(value = "请求头token",required = true)@RequestHeader String token) {
        ResponseVO inserts = this.personService.insertAssembleData(token, person);
        return   inserts;
    }

**@RequestBody注解标识的只能用@PostMapping不然swagger要报错!真他娘坑 **

 @ApiOperation(value = "分页查询")
    @PostMapping("/searchPage")
    R searchPage(@RequestBody PageDTO pageDTO) {
        return securityParamService.searchPage(pageDTO);
    }