Swagger和knife4j的使用

最新推荐文章于 2024-03-28 17:05:22 发布
最新推荐文章于 2024-03-28 17:05:22 发布
阅读量929 收藏 6
点赞数 1
文章标签： java spring boot 开发语言
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/m0_54070163/article/details/129270090
版权

文章目录

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>

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();
    }
}

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;
}
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 "删除成功";
    }
}

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>

引入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();
    }
}

2.3 创建yaml配置文件

# 增强功能
knife4j:
  enable: true

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

创建控制层：

@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 "删除成功";
    }
}

2.5 效果演示

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

在这里插入图片描述

海苔大王
关注
  • 1
    点赞
  • 踩
  • 6
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
超简单配置接口文档Swagger和Knife4j教程
搬砖农民工的博客
07-30 5853
如何配置Swagger 3.0和Knife4j 3.0版本，建议使用Knife4j，因为它的前身是swagger-bootstrap-ui，是在Swagger的基础上进行了界面的优化
再见丑陋的 SwaggerUI，这款开源的API文档生成神器界面更炫酷，逼格更高
沉默王二
02-10 2万+
一般在使用 Spring Boot 开发前后端分离项目的时候，都会用到 Swagger。Swagger 是一个规范和完整的框架，用于生成、描述、调试和可视化 RESTful 风格的 Web API 服务框架。 但随着系统功能的不断增加，接口数量的爆炸式增长，Swagger 的使用体验就会变得越来越差，比如请求参数为 JSON 的时候没办法格式化，返回结果没办法折叠，还有就是没有提供搜索功能。 刚好最近发现 Knife4j 弥补了这些不足，赋予了 Swagger 更强的生命力，于是就来给大家安利一波。 一、
【实战】springboot整合swagger及knife4j
最新发布
勤于笔记，成于点滴。
03-28 1396
一个好的API文档不仅仅能够提供给测试人员编写测试用例，也能够直接给前端使用查阅，可以避免很多在系统集成过程中的问题。这不，最近在整合架构的时候留意到了swagger和knife4j。本身swagger提供的web界面可以很好的调试和查阅，现在加上knife4j的API文档自动生成功能，简直不要太好。那么，今天就分享一期springboot整合swagger及knife4j吧！各位大大敬请鉴赏。
Swagger-knife4j攻略（国产超强swagger文档）
此成非彼诚博客
11-19 7146
Swagger-knife4j攻略
Swagger与knife4j接口测试工具
赵广陆
02-16 1588
目录1 传统测试工具postman2 Swagger介绍3 knife4j 1 传统测试工具postman (1)简介 这个工具测试有所弊端要自己填充一些测试数据才可以非常麻烦 Postman是一款功能强大的网页调试与发送网页HTTP请求的Chrome插件。postman被500万开发者和超100,000家公司用于每月访问1.3亿个API。java开发通常是作为后台开发语言，通常的项目中的接 口开发需要一款测试工具来调试接口，这样无需前端页面也不耽误后台代码的开发进度，postman作为 一个
Swagger 使用指南『Knife4j』
ReturnTmp的博客
09-05 3338
注意：需要添加@EnableSwagger2，@EnableKnife4j两个注解。4.在过滤器中设置不需要处理的路径。1.导入maven依赖。2.配置config。
Swagger与knife4j接口文档组件详解
Cheney的博客
06-25 1384
相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。
Swagger和knife4j_swagger_Swagger和knife4j_knife4jswagger_
09-30
介绍了Swagger和knife4j的使用有代码，有截图，清晰易懂
Swagger和Knife4j
05-04
Swagger 是一个规范且完整的框架，用于生成、描述、调用和...Knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!
spring boot 集成swagger+knife4j，集成mybatis-plus和代码生成器
10-28
spring boot快速上手示例，集成了swagger+knife4j接口文档，集成mybatis-plus持久化，统一的数据返回封装，集成mybatis-plus-generator代码生成器，加入了lombok框架，一个完成的sping boot 示例项目，简单易上手
Springboot使用Knife4j
03-16
Springboot使用Knife4j
swagger文档以及knife4j文档
04-02
通过SpringBoot集成Api文档（Swagger文档）和（knife4j文档）。启动项目后 Swaggger文档访问地址：localhost:8888/swagger-ui.html knife4j文档访问地址:localhost:8888/doc.html
swagger(Knife)配置
m0_72075879的博客
10-11 463
Swagger(Knife)配置
SpringBoot整合knife和swagger3
ljj19990804的博客
07-25 1263
Springboot整合Swagger和knife！一看就会，一做就费！
swagger2的全新UI组件Knife4j
Muscleheng的博客
04-08 4531
前后端对接，就得有一个好的的接口文档，具体到：接口的名称，说明，入参字段，出参字段，是否必传，参数类型等等，这里记录一下使用的swagger ui组件 knife4j-spring-ui。 knife4j-spring-ui 是swagger的一个增强版，相比官方ui，其界面更美观，功能更强大，字段说明更清晰直观，测试起来更方便 对比一下： 官方UI： 全新UI： 集成在sprintboot项目中 一、pom文件添加依赖 <!-- 封装了swagger2 -->.
给Swagger换了个新皮肤，瞬间高大上了
weixin_47083537的博客
07-21 921
Swagger作为一款API文档生成工具，虽然功能已经很完善了，但是还是有些不足的地方。偶然发现knife4j弥补了这些不足，赋予了Swagger更多的功能，今天我们来讲下它的使用方法。 knife4j简介 knife4j是springfox-swagger的增强UI实现，为Java开发者在使用Swagger的时候，提供了简洁、强大的接口文档体验。knife4j完全遵循了springfox-swagger中的使用方式，并在此基础上做了增强功能，如果你用过Swagger，你就可以无缝切换到knife4j。.
Knife4j使用教程（三） -- 实体类的配置注解（@ApiModel与@ApiModelProperty 的 认识与使用）
PUYALEI的博客
10-27 1245
Knife4j使用教程（三） -- 实体类的配置注解（@ApiModel与@ApiModelProperty 的 认识与使用）
精雕细琢的文档体验：Spring Boot 与 Knife4j 完美交汇
热门推荐
todoitbo的博客
02-05 4万+
本文将深入探讨在 Spring Boot 项目中整合 Knife4j，这是一种基于 Swagger 的文档工具。通过使用 Knife4j，你可以轻松生成清晰、美观的 API 文档，提升你的项目文档管理水平。文章从基础概念到高级特性，带你领略 Knife4j 的独特魅力。
swagger和knife4j
07-28
Swagger和Knife4j都是用于API文档生成和展示的工具。 Swagger是一个规范和工具集，用于描述、构建、发布和维护 RESTful 风格的 Web服务。它可以根据代码注解生成API文档，并提供了一个可交互的UI界面来浏览和测试...

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值