Swagger3+knife4j的使用

港控/mmm° 2023-09-28 16:09 147阅读 0赞

## Swagger3+knife4j的使用 ##

## 一、导包 ##

<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-boot-starter</artifactId>
                <version>3.0.0</version>
            </dependency>
    
            
            <dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>knife4j-spring-boot-starter</artifactId>
                <version>3.0.3</version>
            </dependency>

## 二、写配置类 ##

@Configuration
    @EnableOpenApi
    public class SwaggerConfig {
        
    
        @Bean
        public Docket initDocket(Environment env) {
        
    
            //设置要暴漏接口文档的配置环境
            //设置要显示的Swagger环境
            Profiles profile = Profiles.of("test","dev");
            //获取项目的环境：
            //通过environment.acceptsProfiles判断是否处在自己设定的环境当中
            boolean flag = env.acceptsProfiles(profile);
            return new Docket(DocumentationType.OAS_30)
                    .apiInfo(apiInfo())
                    .enable(flag)//是否启动swagger 默认为true ,如果为false，则Swagger不能再浏览器中访问
                    .select()
                    //RequestHandlerSelectors,配置要扫描接口的方式
                    .apis(RequestHandlerSelectors.basePackage("com.zdsoft.datafactory.controller")) //指定要扫描的包
    //                .apis(RequestHandlerSelectors.any())   //扫描全部
                    //.apis(RequestHandlerSelectors.none()):不扫描
                    //.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)):扫描类上的注解，参数是一个注解的反射对象
                    //.apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)):扫描方法上的注解
    //                .apis(RequestHandlerSelectors.basePackage("com.zhao.controller"))
                    //paths()过滤什么路径(url)
                    //paths(PathSelectors.ant("/zhao/**")) 就是在localhost:8080/zhao  后面的路径
    //                .paths(PathSelectors.ant("/zhao/**"))
    //                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    .paths(PathSelectors.any())
                    .build()
                    //右上角 组（有几个Docket，有几个组）
                    .groupName("第一组");
        }
    
        private ApiInfo apiInfo() {
        
            return new ApiInfoBuilder()
                    .title("第一组的Swagger3-接口文档")
                    .description("第一组")
                    .contact(new Contact("第一组", "https://blog.csdn.net/qq_57581439?type=blog", "XXXX@qq.com "))
                    .version("V1.0")
    //                .license("Apache 2.0")
                    .build();
        }
    }

## 三、测试 ##

浏览器访问http://localhost:8080/swagger-ui/即可访问到swagger3初始页面

![在这里插入图片描述][fc942e69569a4b118e7bc1b3caaa058a.png]

浏览器访问http://localhost:8080/doc.html即可访问knife4j初始页面

![在这里插入图片描述][13efed46d38544d5b3d31c4977abeb18.png]

## 四、swagger2注解 ##

### 4.1 类 ###

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

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

### 4.2 方法上 ###

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

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

### 4.3 方法入参 ###

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

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

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

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

### 4.4 实体 ###

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

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

###### @ApiModelProperty描述一个model的属性 ######

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

### 4.5 header参数 ###

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

### 4.6 file入参 ###

需要使用@RequestPart 注解

@ApiOperation(value = "上传文件接口",notes = "上传文件接口")
        @ApiImplicitParams({
        
                @ApiImplicitParam(name = "name", value = "上传人")
        })
        @PostMapping(value = "/uploadFile")
        public String uploadFile(
        @RequestParam("name") String name,
        @RequestPart("file") MultipartFile file){
        
            
        }

## 五、swagger3注解与2相差很多，但也兼容了2的注解，区别如下 ##

<table> 
 <thead> 
  <tr> 
   <th>swagger2</th> 
   <th>swagger3</th> 
   <th>注解位置</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@Api</td> 
   <td>@Tag(name=“接口类描述”)</td> 
   <td>Controller类上</td> 
  </tr> 
  <tr> 
   <td>@ApiOperation</td> 
   <td>@Operation(summary=“接口方法描述”)</td> 
   <td>Controller方法上</td> 
  </tr> 
  <tr> 
   <td>@ApiImplicitParams</td> 
   <td>@Parameters</td> 
   <td>Controller方法上</td> 
  </tr> 
  <tr> 
   <td>@ApiImplicitParam</td> 
   <td>@Parameter(descriprion=“参数描述”)</td> 
   <td>Controller方法上<code>@Parameters</code>里</td> 
  </tr> 
  <tr> 
   <td>@ApiParam</td> 
   <td>@Parameter(descriprion=“参数描述”)</td> 
   <td>Controller方法的参数上</td> 
  </tr> 
  <tr> 
   <td>@ApiIgonre</td> 
   <td>@Parameter(hidden=true)或@Operation(hidden=true)或@Hidden</td> 
   <td>-</td> 
  </tr> 
  <tr> 
   <td>@ApiModel</td> 
   <td>@Schema</td> 
   <td>实体类上</td> 
  </tr> 
  <tr> 
   <td>@ApiModelProperty</td> 
   <td>@Schema</td> 
   <td>实体类属性上</td> 
  </tr> 
 </tbody> 
</table>

### 标注在实体类上（与lombok连用） ###

注意这里的属性名只能试小写，有大写的显示不出来，除非把private改为public

@Data
    @ApiModel(value = "用户类",description = "用户")
    public class User {
        
        @Schema(description = "用户名")
        private String username;
        @Schema(description = "密码")
        private String password;
    }

解决办法（手动加get、set方法）

@Data
    @ApiModel(value = "用户类",description = "用户")
    public class User {
        
        @Schema(description = "用户名")
        private String userName;
        @Schema(description = "密码")
        private String passWord;
    
        public String getUserName() {
        
            return userName;
        }
    
        public void setUserName(String userName) {
        
            this.userName = userName;
        }
    
        public String getPassWord() {
        
            return passWord;
        }
    
        public void setPassWord(String passWord) {
        
            this.passWord = passWord;
        }
    }

### 标注在控制器上： ###

@RestController
    @Api(tags = "用户信息处理")
    public class HelloController {
        
        @GetMapping("/user")
        @ApiOperation("这里写这个是干嘛的，方便swagger中看，就是和上面@Role中内容写一样就行")
        //这里写入参(如果传的是实体类就不需要写@ApiImplicitParams里面的值)
    //    @ApiImplicitParams({@ApiImplicitParam(name = "username", value = "用户名",required = true),
    //            @ApiImplicitParam(name = "password", value = "密码")})
        public R<StopWatch> ok(@RequestBody StopWatch stopWatch){
        
            System.out.println(stopWatch);
            StopWatch stopWatch1 = new StopWatch();
            stopWatch1.setsId(1L);
            return R.Success(stopWatch1);
    }

## 六、拦截器放行 ##

@Configuration
    public class WebConfig implements WebMvcConfigurer {
        
    
        @Autowired
        TokenInterceptor tokenInterceptor;
    
        /**
         * 拦截器
         * @param registry
         */
        @Override
        public void addInterceptors(InterceptorRegistry registry) {
        
            // 注册token拦截器
            registry.addInterceptor(tokenInterceptor)
                    .addPathPatterns("/**")
                    .excludePathPatterns("/doc.html")
                    .excludePathPatterns("/**/swagger-ui/**")
                    .excludePathPatterns("/**/swagger-resources/**")
                    .excludePathPatterns("/**/v3/**")
            ;
        }
    }

参考文章：[Swagger 使用总结\_sunny\_1100的博客-CSDN博客][Swagger _sunny_1100_-CSDN]  
参考文章：[Spring boot集成Swagger3\_跳着迪斯科学Java的博客-CSDN博客\_swagger3依赖][Spring boot_Swagger3_Java_-CSDN_swagger3]

[fc942e69569a4b118e7bc1b3caaa058a.png]: https://img-blog.csdnimg.cn/fc942e69569a4b118e7bc1b3caaa058a.png
[13efed46d38544d5b3d31c4977abeb18.png]: https://img-blog.csdnimg.cn/13efed46d38544d5b3d31c4977abeb18.png
[Swagger _sunny_1100_-CSDN]: https://blog.csdn.net/L_994572281_LYA/article/details/120259692
[Spring boot_Swagger3_Java_-CSDN_swagger3]: https://blog.csdn.net/weixin_45834777/article/details/115630399