SpringBoot整合knife4j3.0.3实现过程

 更新时间:2026年01月08日 14:34:41   作者:jpq+  
文章介绍了如何在SpringBoot项目中使用Swagger和Knife4j来生成和增强API文档,Swagger通过注解自动生成API文档,而Knife4j则提供了更丰富的功能,如在线调试、多语言支持和离线文档导出等,通过配置和使用这些工具,可以提高API文档的管理和使用效率

在Spring Boot项目中,我们可以通过引入Swagger依赖,然后在Controller中加入相应注解,即可生成API文档。Swagger提供了一个Web界面,在这个界面上可以查看所有API的信息,包括请求方法、参数、响应码等。

Knife4j是Swagger-UI的增强版,它是在Swagger-UI的基础上进行了改进和优化,提供了更加完善的交互体验和更加美观的UI设计。同时,它也提供了更多的扩展功能,例如在线调试和多语言支持等。

配置

pom.xml:

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

Swagger使用

在Spring Boot项目中,Controller通常会有多个接口,我们可以通过在Controller类上添加@Api注解来为API接口添加描述信息,以及使用@ApiOperation注解来为单个接口添加描述信息。

使用

在Spring Boot项目中,我们可以通过Swagger注解@Api来定义接口分组。@Api注解指定了该Controller的标签为“用户管理”,这个标签将作为接口分组的名称::

@RestController
@RequestMapping("/users")
@Api(tags = "用户管理")
public class UserApi {
   
}

当一个Controller包含多个接口时,可以通过@ApiOperation注解指定每个接口的简介和说明。例如:

@RestController
@RequestMapping("/users")
@Api(tags = "用户管理")
public class UserApi {

    @GetMapping("/{id}")
    @ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息")
    public User getUserById(@PathVariable("id") Long id) {
       
    }

    @PostMapping
    @ApiOperation(value = "创建用户", notes = "创建新用户")
    public User createUser(@RequestBody User user) {
       
    }

    // ...
}

此外,设置项目的基本信息也是有必要的。

@EnableOpenApi
@Configuration
public class DocumentConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.jp"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("管理平台API文档")
                .description("管理系统")
                .contact(new Contact("jp", "", ""))
                .version("2.0.0")
                .build();
    }
}

打开API文档地址:

接口字段说明

Swagger提供了@ApiImplicitParam注解。

下面演示使用@ApiImplicitParam注解指定了每个参数的名称、类型和说明:

@RestController
@RequestMapping("/users")
@Api(tags = "用户管理")
public class UserApi {

    @GetMapping("/{id}")
    @ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
    public User getUserById(@PathVariable("id") Long id) {
        // ...
    }

    @PostMapping
    @ApiOperation(value = "创建用户", notes = "创建新用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "user", value = "用户实体", required = true, dataType = "User", paramType = "body")
    })
    public User createUser(@RequestBody User user) {
        // ...
    }

    // ...
}

Knife4j 增强功能

  • 离线文档导出: 用户可以直接在界面上导出 HTML、Markdown 或 Word 格式的离线文档,这对于没有网络环境下的开发、分享或者存档非常有用。
  • 接口排序与分组: Knife4j 支持对API接口进行自定义排序和分组,使得文档结构更加清晰有序,方便用户快速定位到所需接口。
  • 在线调试与数据模拟: 除了基本的接口调用测试外,Knife4j 还增强了在线调试功能,支持设置请求头、Cookie、Body等多种参数,以及保存历史请求、导入导出测试数据等,便于开发者快速验证API功能。
  • 登录认证支持: 为了保护API文档的安全,Knife4j 支持多种登录认证方式(如Basic Auth、OAuth2等),可以对接企业的统一认证系统,确保只有授权用户才能访问API文档。
  • 国际化支持: 内置多语言支持,可以根据用户浏览器的语言偏好自动切换界面语言,提高国际团队的协作效率。

总结

Spring Boot与Knife4j 3.0.3的整合,是提升API管理水平和团队协作效率的有效手段。

它不仅简化了API文档的创建和维护工作,还通过增强的功能特性,为开发者和API使用者带来了前所未有的便利。

无论是对于快速发展的创业公司还是大型企业级项目,这种整合都是构建高质量API不可或缺的一部分。

以上为个人经验,希望能给大家一个参考,也希望大家多多支持脚本之家。

相关文章

  • spring-boot实现增加自定义filter(新)

    spring-boot实现增加自定义filter(新)

    本篇文章主要介绍了spring-boot实现增加自定义filter(新),小编觉得挺不错的,现在分享给大家,也给大家做个参考。一起跟随小编过来看看吧
    2017-05-05
  • Spring Boot 整合 Fisco Bcos的案例分析(区块链)

    Spring Boot 整合 Fisco Bcos的案例分析(区块链)

    本篇文章介绍的 Spring Boot 整合 Fisco Bcos的案例,是在阿里云服务器上部署验证的。大家可根据自己的电脑环境,对比该案例进行开发即可,具体案例代码跟随小编一起看看吧
    2022-01-01
  • vue+springboot+shiro+jwt实现登录功能

    vue+springboot+shiro+jwt实现登录功能

    这篇文章主要介绍了vue+springboot+shiro+jwt实现登录功能,本文通过示例代码给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价值,需要的朋友可以参考下
    2022-04-04
  • Java简单实现定时器

    Java简单实现定时器

    这篇文章主要为大家详细介绍了Java简单实现定时器,文中示例代码介绍的非常详细,具有一定的参考价值,感兴趣的小伙伴们可以参考一下
    2021-04-04
  • 详解解密Java中的类型转换问题

    详解解密Java中的类型转换问题

    这篇文章主要介绍了Java中的类型转换问题,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
    2019-03-03
  • 基于spring @Cacheable 注解的spel表达式解析执行逻辑

    基于spring @Cacheable 注解的spel表达式解析执行逻辑

    这篇文章主要介绍了spring @Cacheable 注解的spel表达式解析执行逻辑,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教
    2022-01-01
  • Java超详细介绍封装与访问控制修符

    Java超详细介绍封装与访问控制修符

    封装是一个非常广泛的概念,小到一个属性的封装,大到一个框架或者一个项目的封装,文中通过实例代码将详细介绍封装与访问控制修饰符
    2022-05-05
  • 深入理解Java8新特性之Stream API的终止操作步骤

    深入理解Java8新特性之Stream API的终止操作步骤

    Stream是Java8的一大亮点,是对容器对象功能的增强,它专注于对容器对象进行各种非常便利、高效的 聚合操作(aggregate operation)或者大批量数据操作。Stream API借助于同样新出现的Lambda表达式,极大的提高编程效率和程序可读性,感兴趣的朋友快来看看吧
    2021-11-11
  • RestTemplate自定义请求失败异常处理示例解析

    RestTemplate自定义请求失败异常处理示例解析

    这篇文章主要为大家介绍了RestTemplate自定义请求失败异常处理的示例解析,有需要的朋友可以借鉴参考下,希望能够有所帮助,祝大家多多进步早日升职加薪
    2022-03-03
  • MyBatis中使用$和#所遇到的问题及解决办法

    MyBatis中使用$和#所遇到的问题及解决办法

    这篇文章主要介绍了MyBatis中使用$和#所遇到的问题及解决办法的相关资料,非常不错,具有参考借鉴价值,需要的朋友可以参考下
    2016-08-08

最新评论