当前位置:   article > 正文

Swagger和knife4j的使用_如何使用swagger+knife4j

如何使用swagger+knife4j


knife4j是加强的swagger文档,功能更加完善,所以需要了解knife4j的朋友可以直接跳转到第二部分。

一、Swagger概述及使用

1.概述

Swagger 是一个规范和完整的框架,用于接口文档的在线自动生成,我们常使用Swagger-ui,一个无依赖的HTML、js和CSS的集合,可以为Swagger兼容API动态生成优雅的文档。

2.使用说明

2.1 添加swagger的依赖

	<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>
  • 1
  • 2
  • 3
  • 4
  • 5

2.2.创建Swagger配置类(随用随复制)

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;


/**
 * Swagger2配置类
 * 在与spring boot集成时,放在与Application.java同级的目录下。
 * 通过@Configuration注解,让Spring来加载该类配置。
 * 再通过@EnableSwagger2注解来启用Swagger2。
 */

@Configuration
@EnableSwagger2
public class Swagger {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息(这些基本信息会展现在文档页面中)
     * 访问地址:http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("使用Swagger2构建RESTful APIs)")
                .description("海苔大王")
                .termsOfServiceUrl("https://blog.csdn.net/m0_54070163")
                .contact(new Contact("海苔大王","https://blog.csdn.net/m0_54070163","feihaitai@email.com"))
                .version("1.0")
                .build();
    }
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
  • 53
  • 54
  • 55

2.3 在项目中的注释

使用到的注解及其说明:

@Api:用在类上面,说明当前类的作用
@ApiOperation:注解来给API增加方法说明
@ApiImplicitParams:用来注解来给方法入参增加说明
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如400
message:信息,例如"请添加参数"
response:抛出异常的类
@ApiModel:@ApiModelProperty:描述一个model的属性

2.4 使用时遇到的错误

swagger Failed to start bean ‘documentationPluginsBootstrapper’; nested exception is java.lang.NullPointerException

原因:spring boot2.6.X 继承swagger报错,因为Springfox使用的路径匹配是基于AntPathMatcher的,而Spring Boot 2.6.X使用的是PathPatternMatcher。

解决办法:在application.properties或者application.yaml中添加

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

2.5 例子

2.5.1 实体类中的使用
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "User的对象",description = "用户信息表")
public class User implements Serializable {
    @ApiModelProperty(value = "用户编号")
    private Integer uid;
    @ApiModelProperty(value = "用户名")
    private String uname;
    @ApiModelProperty(value = "用户密码")
    private String upassword;
    @ApiModelProperty(value = "用户住址")
    private String uaddress;
    @ApiModelProperty(value = "用户身份证号")
    private String uIdCard;
    @ApiModelProperty(value = "用户手机号")
    private String phoneNumber;
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
2.5.2 控制类中的使用
@RestController
@Api(tags = {"用户接口模块"})
@Slf4j
public class UserController {
    /**
     * 添加用户
     *
     * 在使用对象封装参数进行传参时,需要在该对象添加注解,将其注册到swagger中
     *
     * 注意: 在后台采用对象接收参数时,Swagger自带的工具采用的是JSON传参,
     *     测试时需要在参数上加入@RequestBody,正常运行采用form或URL提交时候请删除。
     *
     * @param user 用户类对象
     * @return
     * @throws Exception
     */
    @ResponseBody
    @RequestMapping(value="/doctor",  method= RequestMethod.POST )
    @ApiOperation(value="添加用户信息", notes="添加用户接收对象")
    public String addDoctor(@RequestBody User user) throws Exception{
        if(null == user || user.getUid() == null){
            log.info("添加用户失败");
        }
        try {
            System.out.println("成功----------->"+user.getUname());
        } catch (Exception e) {
            log.info("添加用户失败");
        }

        return user.toString();
    }

    /**
     * 删除用户
     * @param uid 用户ID
     * @return
     */
    @ResponseBody
    @RequestMapping(value="/doctor/{doctorId}",  method= RequestMethod.DELETE )
    @ApiOperation(value="删除用户信息", notes="返回字符串删除失败或删除成功")
    @ApiImplicitParam(paramType="query", name = "uid", value = "用户ID", example = "11",required = true, dataType = "int",dataTypeClass = Integer.class)
    public String deleteDoctor(@RequestParam Integer uid){
        if(uid > 2){
            return "删除失败";
        }
        return "删除成功";
    }
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48

2.6 效果演示

访问 :http://ip地址:端口号/swagger-ui/index.html

首页演示:

在这里插入图片描述

接口控制模块:

在这里插入图片描述

接口模块详情:

在这里插入图片描述

实体类:

在这里插入图片描述

二、knife4j概述及使用(目前最实用!!!)

1.概述

knife4j是swagger的增强版本,更加的小巧、轻量,功能也是更加的完善,UI也更加的清晰;可以从swagger到knife4j无缝切换。

2.knife4j的使用

2.1 添加knife4j的依赖

		<dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.2</version>
        </dependency>
  • 1
  • 2
  • 3
  • 4
  • 5

引入knife4j之后,会自动引入swagger的相关依赖,要注意避免发生依赖冲突

2.2 创建配置类(与swagger的一致即可)

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;


/**
 * Swagger2配置类
 * 在与spring boot集成时,放在与Application.java同级的目录下。
 * 通过@Configuration注解,让Spring来加载该类配置。
 * 再通过@EnableSwagger2注解来启用Swagger2。
 */

@Configuration
@EnableSwagger2
public class Swagger {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息(这些基本信息会展现在文档页面中)
     * 访问地址:http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("使用Swagger2构建RESTful APIs)")
                .description("海苔大王")
                .termsOfServiceUrl("https://blog.csdn.net/m0_54070163")
                .contact(new Contact("海苔大王","https://blog.csdn.net/m0_54070163","feihaitai@email.com"))
                .version("1.0")
                .build();
    }
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
  • 53
  • 54
  • 55

2.3 创建yaml配置文件

# 增强功能
knife4j:
  enable: true
  • 1
  • 2
  • 3

2.4 创建实体类和控制类(使用Swagger中用到的)

创建实体类

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "User的对象",description = "用户信息表")
public class User implements Serializable {
    @ApiModelProperty(value = "用户编号")
    private Integer uid;
    @ApiModelProperty(value = "用户名")
    private String uname;
    @ApiModelProperty(value = "用户密码")
    private String upassword;
    @ApiModelProperty(value = "用户住址")
    private String uaddress;
    @ApiModelProperty(value = "用户身份证号")
    private String uIdCard;
    @ApiModelProperty(value = "用户手机号")
    private String phoneNumber;
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18

创建控制层:

@RestController
@Api(tags = {"用户接口模块"})
@Slf4j
public class UserController {
    /**
     * 添加用户
     *
     * 在使用对象封装参数进行传参时,需要在该对象添加注解,将其注册到swagger中
     *
     * 注意: 在后台采用对象接收参数时,Swagger自带的工具采用的是JSON传参,
     *     测试时需要在参数上加入@RequestBody,正常运行采用form或URL提交时候请删除。
     *
     * @param user 用户类对象
     * @return
     * @throws Exception
     */
    @ResponseBody
    @RequestMapping(value="/doctor",  method= RequestMethod.POST )
    @ApiOperation(value="添加用户信息", notes="添加用户接收对象")
    public String addDoctor(@RequestBody User user) throws Exception{
        if(null == user || user.getUid() == null){
            log.info("添加用户失败");
        }
        try {
            System.out.println("成功----------->"+user.getUname());
        } catch (Exception e) {
            log.info("添加用户失败");
        }

        return user.toString();
    }

    /**
     * 删除用户
     * @param uid 用户ID
     * @return
     */
    @ResponseBody
    @RequestMapping(value="/doctor/{doctorId}",  method= RequestMethod.DELETE )
    @ApiOperation(value="删除用户信息", notes="返回字符串删除失败或删除成功")
    @ApiImplicitParam(paramType="query", name = "uid", value = "用户ID", example = "11",required = true, dataType = "int",dataTypeClass = Integer.class)
    public String deleteDoctor(@RequestParam Integer uid){
        if(uid > 2){
            return "删除失败";
        }
        return "删除成功";
    }
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48

2.5 效果演示

访问 :http://localhost:8080/doc.html

在这里插入图片描述

声明:本文内容由网友自发贡献,不代表【wpsshop博客】立场,版权归原作者所有,本站不承担相应法律责任。如您发现有侵权的内容,请联系我们。转载请注明出处:https://www.wpsshop.cn/w/花生_TL007/article/detail/93445
推荐阅读
相关标签
  

闽ICP备14008679号