提供了编程的基础技术教程

zl程序教程

您现在的位置是：首页 >  其它

当前栏目

Swagger的增强，knife4j的使用

增强 swagger 使用
2023-09-27 14:24:00 时间 
1. @Api: 用在请求的类上，表示对类的说明

tags="说明该类的作用，可以在前台界面上看到的注解"
value="该参数无意义，在UI界面上看不到，不需要配置"
@Api是Swagger的注解。

该注解用于Controller类上，表示对类的说明

@Api(value = "文章标签")
public class TagsController {
    ...
}
这个注解有两个参数：value、tags

 

0.彻底搞懂SwaggerKnife4j使用方法

 
Bean
public Docket docket(ApiInfo apiInfo){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo)
            //通过.select()方法配置扫描接口
            .select()
            /*
                RequestHandlerSelectors 配置如何扫描接口
                any()：全部扫描（项目中的所有接口）
                none()：不扫描
                basePackage：扫描指定包下的接口
                withClassAnnotation：扫描带有指定注解的类
                withMethodAnnotation：扫描带有指定注解的方法
            */
            .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))//扫描RestController修饰的所有类
　　　　　 //.apis(RequestHandlerSelectors.basePackage("com.xxx.project.web.controller"))//扫描com.xxx.project.web.controller包下的所有类
　　　　　　.build();
}

 

 

1. Swagger的增强，knife4j的使用

https://blog.csdn.net/qq_45632313/article/details/109777131

 

2.knife4j教程

https://doc.xiaominfo.com/docs/features/accesscontrol

 

 

 

_______________________________________________________________________________________________________

Swagger环境搭建及使用(查看参数相关)

 https://blog.csdn.net/qq_44002865/article/details/106021428

 

1、环境搭建

第一步：创建SpringBoot项目并引入依赖

<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>

 

 

第二步：编写Controller类

@RestController  //Bean中的注解
public class controllerTest {
    //Get请求
    @GetMapping("fzkGet")
    public String fzkGet(){
        return "fzkGet";
    }

    //Post请求
    @PostMapping("fzkPost")
    public String fzkPost(){
        return "fzkPost";
    }

    //Put请求
    @PutMapping("fzkPut")
    public String fzkPut(){
        return "fzkPut";
    }

    //Delete请求
    @DeleteMapping("fzkDelete/{id}")
    public String fzkDelete(@PathVariable String id){
        return "fzkDelete";
    }
}

 

 

第三步：编写Swagger配置类并加入 @EnableSwagger2 注解

@Configuration  //配置类
@EnableSwagger2  //swagger注解
public class SwaggerConfig {
}

 

 

第四步：在主配置文件中添加注解扫描

Controller类 和 Swagger类 都在 com.itfzk 包下（com.itfzk包是自己定义的包）

 

@SpringBootApplication
@ComponentScan(basePackages = {"com.itfzk"})  //开启注解扫描
public class Test100Application {
    public static void main(String[] args) {
        SpringApplication.run(Test100Application.class, args);
    }
}

 

 

第五步：访问测试

地址： http://localhost:8080/swagger-ui.html (localhost:8080是自己的ip地址和端口号，swagger-ui.html是显示的页面)

 

效果图

 

 

 

2、使用

配置Swagger

1、Swagger实例Bean是Docket，通过配置Docket实例来配置Swaggger

2、通过apiInfo()属性配置文档信息

 

@Configuration  //配置类

@EnableSwagger2  //swagger注解

public class SwaggerConfig {

 

    @Bean  //配置docket以配置Swagger具体参数

    public Docket webApiConfig(){

        return new Docket(DocumentationType.SWAGGER_2)

                .groupName("fzk")  //分组信息

                .apiInfo(webApiInfo());

    }

 

    //配置文档信息

    private ApiInfo webApiInfo(){

        //联系人信息

        Contact contact = new Contact("fzk", "https://blog.csdn.net/qq_44002865", "1820713352@qq.com");

        return new ApiInfo(

                "Swagger测试",  //标题

                "演示如何配置使用Swagger",  //描述

                "v1.0",  //版本

                "urn:tos",  //服务条件

                contact,  //联系人信息

                "Apache 2.0",  //许可

                "http://www.apache.org/licenses/LICENSE-2.0",  //许可链接

                new ArrayList<>());  //扩展

    }

} 

测试效果

 

 

 

配置扫描接口
构建Docket时通过 select() 方法配置来扫描接口

apis()
使用方法

.select().apis(RequestHandlerSelectors.[需要扫描的配置]).build();
需要扫描的配置:
basePackage(final String basePackage) ：根据包路径扫描接口
.select().apis(RequestHandlerSelectors.basePackage(“com.itfzk.controller”)).build();
扫描 com.itfzk.controller 包
any() ：扫描所有，项目中的所有接口都会被扫描到
.select().apis(RequestHandlerSelectors.any()).build();
扫描所有
none() ：不扫描接口
.select().apis(RequestHandlerSelectors.none()).build();
不扫描
withMethodAnnotation(final Class<? extends Annotation> annotation) ：通过方法上的注解扫描
.select().apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)).build();
只扫描get请求
withClassAnnotation(final Class<? extends Annotation> annotation) ：通过类上的注解扫描
.select().apis(RequestHandlerSelectors.withClassAnnotation(Controller.class)).build();
只扫描有Controller注解的类中的接口
举例

@Bean //配置docket以配置Swagger具体参数
public Docket webApiConfig(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(webApiInfo())
.select() // 通过.select()方法，配置扫描接口,RequestHandlerSelectors配置扫描接口
.apis(RequestHandlerSelectors.basePackage("com.itfzk.test100.controller")).build();
}

 

paths()
使用方法

.select().paths(PathSelectors.[需要扫描的配置]).build();
需要扫描的配置:
any() ：任何请求都扫描
none() ：任何请求都不扫描
regex(final String pathRegex) ：通过正则表达式控制
ant(final String antPattern) ：通过ant()控制
举例

@Bean //配置docket以配置Swagger具体参数
public Docket webApiConfig(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(webApiInfo())
.select().paths(PathSelectors.ant("/fzk/**")).build();
}

 

配置Swagger开关
通过 enable() 方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了

开发和测试的时候开启，项目运行时就不启动

测试不启用 Swagger

@Bean //配置docket以配置Swagger具体参数
public Docket webApiConfig(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(webApiInfo())
.enable(false); //是否启用swagger，不启用
}

 

测试结果

 

 

配置API分组
如果没有配置分组，默认是default

通过 groupName() 方法即可配置分组

@Configuration //配置类
@EnableSwagger2 //swagger注解
public class SwaggerConfig {

@Bean //配置docket以配置Swagger具体参数
public Docket webApiConfig(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("fzk") //配置分组 
.apiInfo(webApiInfo());
}
}

 

配置多个分组只需要配置多个docket

 

@Configuration //配置类
@EnableSwagger2 //swagger注解
public class SwaggerConfig {

@Bean //配置docket以配置Swagger具体参数
public Docket webApiConfig(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("fzk")
.apiInfo(webApiInfo());
}
@Bean //配置docket以配置Swagger具体参数
public Docket webApiConfig1(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("fzk1")
.apiInfo(webApiInfo1());
}


@Bean //配置docket以配置Swagger具体参数
public Docket webApiConfig2(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("fzk2")
.apiInfo(webApiInfo2());
}
}

 

常用注解
@Api()
用于 Controller 类上；表示标识这个类是swagger的资源

tags ：表示说明
value ：也是说明，可以使用tags替代

@RestController
@Api(tags = "测试Swagger")
public class controllerTest {
}

 

 

 


@ApiOperation()
用于Controller方法；表示一个http请求的操作

value用于方法描述
notes用于提示内容
tags可以重新分组（视情况而用）

@RestController
@Api(tags = "测试Swagger")
public class controllerTest {

@ApiOperation("查询Swagger")
@GetMapping("/find")
public String find() {
return "Swagger";
}
}

 

 

 

 


@ApiParam()
用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）

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

 

@RestController
@Api(tags = "测试Swagger")
public class controllerTest {

@ApiOperation("查询Swagger")
@PostMapping("/findById")
public String find(@ApiParam(name = "id", value = "用户id", required = true) String id) {
return "Swagger";
}
}

 

 

 

 


@ApiModel() & @ApiModelProperty()
@ApiModel()

用于类 ；表示对类进行说明，用于参数用实体类接收
value–表示对象名
description–描述
都可省略
@ApiModelProperty()

用于方法，字段； 表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏

@Data
@ApiModel(value = "User对象", description = "用户")
public class User {
@ApiModelProperty(value = "用户名")
private String userName;

@ApiModelProperty(value = "密码")
private String password;
}

 

 

 

 

  

相关文章