Java、SpringBoot中配置接口文档，knife4j、swagger

最新推荐文章于 2024-05-31 23:03:50 发布
最新推荐文章于 2024-05-31 23:03:50 发布
阅读量1.2k 收藏 18
点赞数 21
分类专栏： java 文章标签： java spring boot 开发语言
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/weixin_46533577/article/details/135183243
版权

Java、SpringBoot中配置接口文档，knife4j、swagger

knife配置

官网：https://doc.xiaominfo.com/

我这里以最新版的为例，SpringBoot版本是3.0.0以上的

需要注意的是自动集成了swagger，每个SpringBoot版本会对应其knfie版本，swagger也一样，如果配置了不同的版本一定要看官网介绍，否则启动时就会报错，亲身经历。

我这里SpringBoot是 3.0.0往上的！！！

如果需要配置，生产环境不开放接口下面也有介绍，也可以设置接口访问密码用户名等。

在这里插入图片描述

在这里插入图片描述

需要在pom.xml中导入以下

使用idea创建完项目直接将下面放进去之后刷新下就可以了，不需要再引入其它东西了，而且也集成了swagger

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

因为这个是SpringBoot 3.0.0以上的所以不需要导入swagger

为了看的清楚我将我pom.xml所有的内容都放进来，如果出错也有个参考

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.1</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>knife4j</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>knife4j</name>
    <description>knife4j</description>
    <properties>
        <java.version>17</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <!-- knife4j -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
            <version>4.3.0</version>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

配置文件中

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
#    分组也可以在 Knife4jConfig 文件目录下胚子
  group-configs:
    - group: 'All API'
      paths-to-match: '/**'
      packages-to-scan: com.example.knife4j

# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  production: true  # 开启生产环境屏蔽，开发测试要设为true否则看不到
  setting:
    language: zh_cn
  basic:
    enable: true
    username: test # Basic认证用户名
    password: 123  # Basic认证密码

目录结构

为了演示清楚些，我将目录结构附上
在这里插入图片描述

配置文件Knife4jConfig

如果在yml配置文件中设置了分组这里也设置了相同的分组会以Knife4jConfig为准，会覆盖掉yml中的。

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class Knife4jConfig {
    // 创建 admin API分组
    @Bean
    public GroupedOpenApi sessionApi() {
        return GroupedOpenApi.builder()
                .group("session接口")
                .pathsToMatch("/session/**")
                .build();
    }

    // 创建 token API分组
    @Bean
    public GroupedOpenApi tokenApi() {
        return GroupedOpenApi.builder()
                .group("token接口")
                .pathsToMatch("/token/**")
                .build();
    }

    // 创建 jwt API分组
    @Bean
    public GroupedOpenApi JWTApi() {
        return GroupedOpenApi.builder()
                .group("jwt接口")
                .pathsToMatch("/jwt/**")
                .build();
    }

    // 配置名称等信息
    @Bean
    public OpenAPI customerOpenApi() {
        return new OpenAPI().info(
                new Info()
                .title("接口文档")
                .version("1.0")
                .contact(new Contact()
                .name("bunny")));
    }
}

写个简单接口测试下DemoController

  • 访问路径为：
    • knife：http://localhost:8080/doc.html
    • swagger：http://localhost:8080/swagger-ui/index.html

注意你自己的路径和端口号。

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Tag(name = "测试接口")
public class DemoController {
    @RequestMapping("hello")
    @Operation(summary = "hello接口", description = "Hello消息描述")
    public String hello() {
        return "Hello";
    }
}

在这里插入图片描述

在丝袜哥中也可以

在这里插入图片描述

Swagger 配置

其实SpringBoot版本高点，直接引入knife也可以看到swagger。

如果想单独设置swagger也可以。

pom.xml中导入

<!-- swagger2 -->
<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>2.2.15</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version>
</dependency>

和上面一样我将里面内容都导入进来好有个对比

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.1</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>swagger</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>swagger</name>
    <description>swagger</description>
    <properties>
        <java.version>17</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <!-- swagger2 -->
        <dependency>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>2.2.15</version>
        </dependency>
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.1.0</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

编写一个简单的接口

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Tag(name = "测试接口")
public class DemoController {
    @RequestMapping("hello")
    @Operation(summary = "hello接口", description = "Hello消息描述")
    public String hello() {
        return "Hello";
    }
}

在这里插入图片描述

Bunny0212
关注
  • 21
    点赞
  • 踩
  • 18
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
专栏目录
java接口文档规范
06-01
文档为md格式
swagger文档以及knife4j文档
04-02
通过SpringBoot集成Api文档（Swagger文档）和（knife4j文档）。启动项目后 Swaggger文档访问地址：localhost:8888/swagger-ui.html knife4j文档访问地址:localhost:8888/doc.html
springboot3 knife4j在线接口API文档篇
TheOne的博客
12-20 480
OpenAPI 3.0.0 是 OpenAPI 规范的第一个正式版本，因为它是由 SmartBear Software 捐赠给 OpenAPI Initiative，并在2015年从 Swagger 规范重命名为 OpenAPI 规范。springboot3相当于springboot2很多以往正常的依赖都无法直接使用，由于oracle开源协议的更新javax变成了Jakarta，所有依赖项从 Java EE 迁移到 Jakarta EE API。knife4j就是国产非常好用的一款ui加强的OpenAPI。
使用knife4j
最新发布
weixin_44060804的博客
05-31 578
1.整合Knife4j2.配置文件配置Knife4j3.代码相关配置4.访问Knife4j接口文档5.执行接口调用测试6.以prod环境 启动项目 访问Knife4j接口文档7.Knife4j传token示例Knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案官网地址。
简单易懂，高效实用的接口文档编写技巧
Gefangenes的博客
06-27 2726
如果文章和代码有表述不当之处，还请不吝赐教。以下是正文！
Java「接口文档」示例
weixin_42862555的博客
02-26 1万+
接口概念 官方解释：Java接口是一系列方法的声明，是一些方法特征的集合，一个接口只有方法的特征没有方法的实现，因此这些方法可以在不同的地方被不同的类实现，而这些实现可以具有不同的行为（功能）。 我的解释：接口可以理解为一种特殊的类，里面全部是由全局常量和公共的抽象方法所组成。接口是解决Java无法使用多继承的一种手段，但是接口在实际中更多的作用是制定标准的。或者我们可以直接把接口理解为100%的抽象类，既接口中的方法必须全部是抽象方法。（JDK1.8之前可以这样理解） 接口的特点 就像一个类一样，一个接口
springboot生成接口文档
weixin_58473601的博客
07-12 3143
springboot生成接口文档
Knife4j--使用教程--配置 详细讲解
Vanhs的博客
08-02 4578
本机springboot版本为2.7.6，因此选择OpenAPI2(Swagger)版本，底层依赖框架为Springfox，Spring Boot 版本在2.4.0~3.0.0之间建议使用OpenAPI2(Swagger)。是基于springboot构建的一个文档生成工具，它可以让开发者为我们的应用生成。启动SpringBoot项目后出现基本就代表配置成功了~，目的是可以更加方便的基于API文档进行测试。
Knife4j各版本集成SpringBoot 2.x 3.x版本demo示例
04-23
Knife4j是一款为Java开发者设计的API文档生成和管理工具，它主要针对Spring Boot和Spring MVC框架，使得开发者能够方便地构建、展示和维护RESTful API文档。在本示例中，我们将探讨如何将Knife4j集成到Spring Boot 2...
SpringBoot使用knife4j进行在线接口调试
09-08
在本文中，我们将深入探讨如何在SpringBoot项目中利用knife4j进行在线接口调试。首先，让我们了解knife4j是什么以及它为何比Swagger更胜一筹。 **knife4j简介** knife4j是针对Java MVC框架的一个增强型Swagger解决...
Springboot使用Knife4j
03-16
而Knife4j则是针对Spring Boot的一款增强工具，主要用于文档的生成和展示，极大地提升了开发者在API接口开发过程中的效率。这篇内容我们将深入探讨如何在SpringBoot项目中有效地使用Knife4j。 首先，我们需要理解...
Springboot2整合knife4j过程解析
08-24
首先，knife4j 是一个基于 Swagger 的接口文档生成工具，它可以帮助开发人员快速生成 API 文档，提高开发效率。Springboot2 是一个流行的 Java 框架，用于构建 Web 应用程序。将 knife4j 与 Springboot2 进行整合...
SpringBoot——SpringBoot生成接口文档
庄小焱
03-30 6979
SpringBoot开发Restful接口，有什么API规范吗？如何快速生成API文档呢？Swagger 是一个用于生成、描述和调用 RESTful 接口的 Web 服务。通俗的来讲，Swagger 就是将项目中所有（想要暴露的）接口展现在页面上，并且可以进行接口调用和测试的服务。本文主要介绍OpenAPI规范，以及Swagger技术栈基于OpenAPI规范的集成方案。
超简单，Java 项目自动生成接口文档教程
04-24 3668
你还在用 word、markdown 埋头苦干写？写文档这件事恐怕是每个开发都万分抗拒的事情了。本篇文章详细教你如何利用插件工具，在 IDEA 中自动生成 API 文档。先来看看从 IDEA 中生成文档的效果如下图。下图是使用 Apifox 插件（Apifox helper）从 IDEA 生成的文档（右）效果。
springboot整合swagger接口文档
2301_77664771的博客
06-26 521
（简称 MP）是一个的增强工具，在 MyBatis 的基础上只做增强不做改变，为简化开发、提高效率而生。愿景我们的愿景是成为 MyBatis 最好的搭档，就像魂斗罗中的 1P、2P，基友搭配，效率翻倍。特点：无侵入：只做增强不做改变，引入它不会对现有工程产生影响，如丝般顺滑损耗小：启动即会自动注入基本 CURD，性能基本无损耗，直接面向对象操作强大的 CRUD 操作：内置通用 Mapper、通用 Service，仅仅通过少量配置即可实现==单表大部分 CRUD 操作。
Knife4j系列--使用-教程-实例-配置 详细讲解
热门推荐
m0_72568513的博客
06-03 1万+
Knife4j是基于springboot构建的一个文档生成工具，它可以让开发者为我们的应用生成API文档，目的是可以更加方便的基于API文档进行测试，生成的文档还可以导出，然后给到前端开发团队，前端开发团队可以基于API接口写具体的调用。
Springboot整合knife4j
Miao的博客
04-18 3510
官方文档版本问题文档注解在项目开发中，自测和联调时，一篇详细通用的接口文档显得尤为重要，不仅提高了开发效率，而且避免了无效沟通，保证了流程的规范性。Knife4j跟Swagger用法基本一样，UI界面设计更加漂亮可用。
Java 后端整合 Swagger 和 Knife4j 接口文档
m0_74059961的博客
01-13 2384
详细介绍了接口的文档的作用和使用方式，并在 SpringBoot 项目中手动整合 Swagger 文档，通过修改 SpringMVC 的配置解决了 SpringBoot 2.6 整合 Swagger 遇到的问题 Failed to start bean 'documentationPluginsBootstrapper'; 并以用户登录接口为例，介绍如何使用功能接口文档进行调试
【框架1-springboot整合Knife4j框架-API文档框架】
m0_55355196的博客
03-23 699
Knife4j是一款基于Swagger 2的在线API文档框架。，可以显示当前程序中指定路径下包含的接口，且可以生成接口doc文档.。
springboot中整合knife4j接口文档
04-30
Spring Boot是一种便捷的框架，它可以快速地搭建Java应用程序，并且它对于集成其他组件和框架也十分方便。而Knife4j则是一种集成度很高的API文档工具，它可以将接口文档在Swagger的基础上大幅度优化。在Spring Boot中使用Knife4j整合API文档也非常简单。 首先，我们需要在Spring Boot的项目中引入Knife4j依赖，可以在pom.xml文件中加入以下代码： ``` <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>2.2.7</version> </dependency> ``` 这样Knife4j就会被自动集成到Spring Boot的应用中。 接下来，我们需要在Controller方法上增加注解，并且配置一些信息才能生成接口文档。 ``` @GetMapping("/hello") @ApiOperation(value = "示例API接口", notes = "这是一个示例API接口") @ApiImplicitParams({ @ApiImplicitParam(name = "name", value = "用户名", required = true, dataType = "String", paramType = "header") }) public String hello(@RequestHeader String name){ return "Hello, " + name + "!"; } ``` 其中@GetMapping是Spring Boot的注解，用于标记这是一个GET请求。@ApiOperation和@ApiImplicitParams则是Knife4j的注解，它们分别用于注释方法和方法参数的信息。 最后，在启动Spring Boot应用后，访问http://localhost:8080/doc.html 就可以看到生成的接口文档了。这个文档列表会列出所有接口的URL、HTTP方法、请求参数、响应结果等信息，非常直观和有用。通过Knife4j可以使API文档生成更加高效、直观，方便开发者理解和调用接口。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

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

抵扣说明：

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

余额充值