一、依赖

添加依赖和spring-boot-starter-parent的版本有关，自动引入的spring-plugin-core包版本不一致会导致项目跑不起来，这里是个大坑，帮你踩了，拿走不谢。

1.1、2.1.x版本

<dependency>

   <groupId>io.springfox</groupId>

   <artifactId>springfox-boot-starter</artifactId>

   <version>3.0.0</version>

   <exclusions>

       <exclusion>

           <artifactId>spring-plugin-core</artifactId>

           <groupId>org.springframework.plugin</groupId>

       </exclusion>

   </exclusions>

</dependency>

<dependency>

   <groupId>org.springframework.plugin</groupId>

   <artifactId>spring-plugin-core</artifactId>

   <version>2.0.0.RELEASE</version>

</dependency>

1.2、2.3.x版本

<dependency>

   <groupId>io.springfox</groupId>

   <artifactId>springfox-boot-starter</artifactId>

   <version>3.0.0</version>

</dependency>

二、配置

2.1、启动类

启动类添加@EnableOpenApi注解，然并卵，经过测试不加也可以(黑人问号脸.jpg)，到底加还是不加，看你心情吧。

@EnableOpenApi

@SpringBootApplication

publicclassSwagger3DemoApplication {

   publicstaticvoidmain(String[] args) {

       SpringApplication.run(Swagger3DemoApplication.class, args);

   }

}

2.2、swagger配置

可以根据Environment和Profiles对象来控制不同环境文档地址是否对外暴漏

@Configuration

publicclassSwaggerConfig {

   @Bean

   publicDocketinitDocket(Environmentenv) {

       //设置要暴漏接口文档的配置环境

       Profilesprofile=Profiles.of("dev", "test");

       booleanflag=env.acceptsProfiles(profile);

       returnnewDocket(DocumentationType.OAS_30)

               .apiInfo(apiInfo())

               .enable(flag)

               .select()

               .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

               .paths(PathSelectors.any())

               .build();

   }

   privateApiInfoapiInfo() {

       returnnewApiInfoBuilder()

               .title("Swagger3-Demo接口文档")

               .description("技术支持-xxx技术团队")

               .contact(newContact("xxx技术团队", "http://www.xxx.com", "xxx@cloud.com "))

               .version("1.0")

               .build();

   }

}

三、常用注解

3.1、类

@Api()：表示这个类是 swagger 资源

• tags：表示说明内容，只写 tags 就可以省略属性名
  
• value：同样是说明，不过会被 tags 替代，没卵用
  

3.2、方法上

@ApiOperation() ：对方法的说明，注解位于方法上

• value：方法的说明
  
• notes：额外注释说明
  
• response：返回的对象
  
• tags：这个方法会被单独摘出来，重新分组，若没有，所有的方法会在一个Controller分组下
  

3.3、方法入参

@ApiParam()：对方法参数的具体说明，用在方法入参括号里，该注解在post请求参数时，参数名不显示

• name：参数名
  
• value：参数说明
  
• required：是否必填
  

@ApiImplicitParam对方法参数的具体说明，用在方法上@ApiImplicitParams之内，该注解在get,post请求参数时，参数名均正常显示

• name 参数名称
  
• value 参数的简短描述
  
• required 是否为必传参数
  
• dataType 参数类型，可以为类名，也可以为基本类型（String，int、boolean等）指定也不起作用，没卵用
  
• paramType 参数的传入（请求）类型，可选的值有path, query, body, header or form。
  

3.4、实体

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

• value model的别名，默认为类名
  
• description model的详细描述
  

@ApiModelProperty描述一个model的属性

• value 属性简短描述
  
• example 属性的示例值
  
• required 是否为必须值
  

3.5、header参数

@ApiImplicitParams({      @ApiImplicitParam(paramType="header",name="USERTOKEN",dataType="String",required=true,value="用户token")

   })

3.6、map入参

这个注解

3.7、file入参

需要使用@RequestPart 注解

@ApiOperation(value="上传文件接口",notes="上传文件接口")

   @ApiImplicitParams({

           @ApiImplicitParam(name="name", value="上传人")

   })

   @PostMapping(value="/uploadFile")

   publicStringuploadFile(@RequestParam("name") Stringname,@RequestPart("file") MultipartFilefile){

       

   }

四、拦截器放行

若项目中有使用拦截器，放行以下路径

@Configuration

publicclassWebConfigimplementsWebMvcConfigurer {

   @Autowired

   TokenInterceptortokenInterceptor;

   /**

    * 拦截器

    * @param registry

    */

   @Override

   publicvoidaddInterceptors(InterceptorRegistryregistry) {

       // 注册token拦截器

       registry.addInterceptor(tokenInterceptor)

               .addPathPatterns("/**")

               .excludePathPatterns("/**/swagger-ui/**")

               .excludePathPatterns("/**/swagger-resources/**")

               .excludePathPatterns("/**/v3/**")

       ;

   }

}

五、文档访问地址

http://ip:port/context-path/swagger-ui/

http://ip:port/context-path/swagger-ui/index.html