Knife4j-SpringBoot3-OpenAPI3：基本使用、生产环境关闭接口文档、配置文件、配置接口文档描述信息、OpenAPI3注解

于 2024-10-08 08:15:00 发布
阅读量891 收藏 20
点赞数 21
分类专栏： # 接口文档 文章标签： knife4j 接口文档 Swagger OpenAPI spring boot
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/sgx1825192/article/details/142721424
版权

版本：

SpringBoot：3.3.3
Knife4j：4.5.0

创建时间：2024-10-08

一、官网

Knife4j 的 SpringBoot3 官方说明文档：

https://doc.xiaominfo.com/docs/quick-start#spring-boot-3

springdoc官网：https://springdoc.org/

二、Knife4j - 基本使用

依赖

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

效果

引入此依赖后，运行应用，此时接口文档页面已经能够打开。

访问接口文档地址：http://ip:port/doc.html
比如，在本地运行的端口号为 9003 的应用，接口文档访问地址为：http://localhost:9003/doc.html

Knife页面

http://localhost:9003/doc.html

Swagger页面

http://localhost:9003/swagger-ui/index.html

三、生产环境关闭接口文档

官网说明

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


配置

knife4j:
  # 开启增强配置
  enable: true
  # 标识是否生产环境：true-生产环境关闭文档，false-显示文档
  production: true

效果

访问接口文档页面，会提示：You do not have permission to access this page

Knife页面

http://localhost:9003/doc.html

Swagger页面

http://localhost:9003/swagger-ui/index.html

查询接口文档（JSON格式）的 API 接口

http://localhost:9003/v3/api-docs

四、配置文件（可选）

springdoc和Knife4j配置

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: '默认分组'
      paths-to-match: '/**'
      packages-to-scan: com.example
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn
    enable-footer: false

接口排序，按照 接口路径 字母顺序排序。

五、配置接口文档描述信息（主页）

接口文档描述信息，配置效果：


@Bean注册OpenAPI

接口文档中 主页（基本信息） 的配置，需要通过Java代码写配置类。

package com.example.knife4j.config;

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.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class Knife4jConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Knife4j示例项目")
                        .description("Knife4j示例项目接口文档的详细描述")
                        .version("V1.0.0")
                        .contact(new Contact().name("宋冠巡"))
                );
    }

}

springdoc的官网文档：

@OpenAPIDefinition注解

package com.example.knife4j.config;

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Contact;
import io.swagger.v3.oas.annotations.info.Info;

@OpenAPIDefinition(info = @Info(title = "Knife4j示例项目", description = "Knife4j示例项目接口文档的详细描述", version = "V1.0.0", contact = @Contact(name = "宋冠巡")))
public class OpenAPIConfig {
}

springdoc的官网文档：


六、OpenAPI3注解

使用OpenAPI3的规范注解，注释接口和数据模型，示例代码如下。

接口注解

package com.example.knife4j.web.user.controller;

import com.example.hello_common.model.vo.UserVo;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.time.LocalDate;
import java.time.LocalDateTime;

@Slf4j
@RestController
@RequestMapping("/users")
@Tag(name = "用户管理")
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "查询用户")
    @Parameter(name = "id", description = "用户ID", example = "1234567890123456789")
    public UserVo getUserById(@PathVariable String id) {
        UserVo vo = new UserVo();
        vo.setId(id);
        vo.setName("张三");
        vo.setMobilePhone("18612345678");
        vo.setEmail("zhangsan@example.com");
        vo.setBeginTime(LocalDateTime.of(2024, 1, 1, 8, 30, 0));
        vo.setEndTime(LocalDateTime.of(2024, 12, 31, 17, 0, 0));
        vo.setBeginDate(LocalDate.of(2024, 1, 1));
        vo.setEndDate(LocalDate.of(2024, 12, 31));
        return vo;
    }

}

数据模型注解

package com.example.hello_common.model.vo;

import io.swagger.v3.oas.annotations.media.ExampleObject;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

import java.time.LocalDate;
import java.time.LocalDateTime;

@Data
@Schema(name = "用户VO")
public class UserVo {

    @Schema(description = "用户ID", example = "1234567890123456789")
    private String id;

    @Schema(description = "姓名", example = "张三")
    private String name;

    @Schema(description = "手机号码", example = "18612345678")
    private String mobilePhone;

    @Schema(description = "电子邮箱", example = "zhangsan@example.com")
    private String email;

    @Schema(description = "开始时间", example = "2024-01-01 08:30:00")
    private LocalDateTime beginTime;

    @Schema(description = "结束时间", example = "2024-12-31 17:00:00")
    private LocalDateTime endTime;

    @Schema(description = "开始日期", example = "2024-01-01")
    private LocalDate beginDate;

    @Schema(description = "结束日期", example = "2024-12-31")
    private LocalDate endDate;

}

接口文档效果

七、附录

UserController

package com.example.knife4j.web.user.controller;

import com.example.hello_common.exception.BusinessException;
import com.example.hello_common.model.param.UserParam;
import com.example.hello_common.model.vo.UserVo;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.*;

import java.time.LocalDate;
import java.time.LocalDateTime;
import java.util.ArrayList;
import java.util.List;

@Slf4j
@RestController
@RequestMapping("/users")
@Tag(name = "用户管理")
public class UserController {

    @PostMapping
    public void addUser(@RequestBody UserParam param) {
        log.info("新增用户。param={}", param);
        boolean isNameExists = generateMockUsers().stream()
                .anyMatch(user -> user.getName() != null && user.getName().equals(param.getName()));
        if (isNameExists) {
            throw new BusinessException(String.format("用户名[%s]已存在", param.getName()));
        }

    }

    @DeleteMapping("/{id}")
    public void deleteUser(@PathVariable String id) {
        log.info("删除用户。id={}", id);
        boolean isIdExists = generateMockUsers().stream()
                .anyMatch(user -> user.getId() != null && user.getId().equals(id));
        if (!isIdExists) {
            throw new BusinessException("用户ID不存在");
        }
    }

    @PutMapping("/{id}")
    public void editUser(@PathVariable String id, @RequestBody UserParam param) {
        log.info("编辑用户。id={}，param={}", id, param);
        boolean isIdExists = generateMockUsers().stream()
                .anyMatch(user -> user.getId() != null && user.getId().equals(id));
        if (!isIdExists) {
            throw new BusinessException("用户ID不存在");
        }
    }

    @GetMapping("/{id}")
    @Operation(summary = "查询用户")
    @Parameter(name = "id", description = "用户ID", example = "1234567890123456789")
    public UserVo getUserById(@PathVariable String id) {
        UserVo vo = new UserVo();
        vo.setId(id);
        vo.setName("张三");
        vo.setMobilePhone("18612345678");
        vo.setEmail("zhangsan@example.com");
        vo.setBeginTime(LocalDateTime.of(2024, 1, 1, 8, 30, 0));
        vo.setEndTime(LocalDateTime.of(2024, 12, 31, 17, 0, 0));
        vo.setBeginDate(LocalDate.of(2024, 1, 1));
        vo.setEndDate(LocalDate.of(2024, 12, 31));
        return vo;
    }

    @GetMapping
    public List<UserVo> listUsers() {
        return generateMockUsers();
    }

    private List<UserVo> generateMockUsers() {
        List<UserVo> list = new ArrayList<>();

        UserVo vo = new UserVo();
        vo.setId("1234567890123456789");
        vo.setName("张三");
        vo.setMobilePhone("18612345678");
        vo.setEmail("zhangsan@qq.com");
        vo.setBeginTime(LocalDateTime.of(2024, 1, 1, 8, 30, 0));
        vo.setEndTime(LocalDateTime.of(2024, 12, 31, 17, 0, 0));
        vo.setBeginDate(LocalDate.of(2024, 1, 1));
        vo.setEndDate(LocalDate.of(2024, 12, 31));
        list.add(vo);

        UserVo vo2 = new UserVo();
        vo2.setId("1234567890123456781");
        vo2.setName("李四");
        vo2.setMobilePhone("13412345678");
        vo2.setEmail("lisi@example.com");
        vo.setBeginTime(LocalDateTime.of(2024, 1, 1, 8, 30, 0));
        vo.setEndTime(LocalDateTime.of(2024, 12, 31, 17, 0, 0));
        vo.setBeginDate(LocalDate.of(2024, 1, 1));
        vo.setEndDate(LocalDate.of(2024, 12, 31));
        list.add(vo2);

        return list;
    }

}

UserVo

package com.example.hello_common.model.vo;

import io.swagger.v3.oas.annotations.media.ExampleObject;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

import java.time.LocalDate;
import java.time.LocalDateTime;

@Data
@Schema(name = "用户VO")
public class UserVo {

    @Schema(description = "用户ID", example = "1234567890123456789")
    private String id;

    @Schema(description = "姓名", example = "张三")
    private String name;

    @Schema(description = "手机号码", example = "18612345678")
    private String mobilePhone;

    @Schema(description = "电子邮箱", example = "zhangsan@example.com")
    private String email;

    @Schema(description = "开始时间", example = "2024-01-01 08:30:00")
    private LocalDateTime beginTime;

    @Schema(description = "结束时间", example = "2024-12-31 17:00:00")
    private LocalDateTime endTime;

    @Schema(description = "开始日期", example = "2024-01-01")
    private LocalDate beginDate;

    @Schema(description = "结束日期", example = "2024-12-31")
    private LocalDate endDate;

}

八、参考

Knife4j 生产环境关闭接口文档 doc.html，亲测有效！

Gitee - 关闭Knife4j

宋冠巡
关注
专栏目录
Knife4j 全局鉴权需求 (在OpenAPI3规范中添加Authorization鉴权请求Header)
iOS逆向与安全
06-11 713
原因： 如果当前OpenAPI3规范中的接口定义并没有security属性对象，那么Knife4j会认为该接口不需要鉴权。解决方案： 借助GlobalOpenApiCustomizer接口，给某一个OpenAPI实例分组下的所有接口添加鉴权方案。在Knife4j的界面将OpenAPI3规范中定义的鉴权方案显示出来，但是在调试界面中并不会显示。参考代码Knife4jJakartaOperationCustomizer.java。参考代码：Knife4jOpenApiCustomizer.java。
【SpringBoot】22、SpringBoot中整合knife4j接口文档
热门推荐
Asurplus
07-02 21万+
在项目开发中，web项目的前后端分离开发，APP开发，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护 接口文档使得项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发，项目维护中或者项目人员更迭，方便后期人员查看、维护 一、界面先赏 1、首页 2、接口文档 3、调试 二、整合 knife4j 1、引入 maven 依赖 <!-- knife4j接口文档 start --> <dependency> &lt
Knife4j各版本集成SpringBoot 2.x 3.x版本demo示例
04-23
Knife4j各版本集成SpringBoot 2.x 3.x版本demo示例，亲测可用 ，仅供学习使用。
Knife4j 生产环境关闭接口文档 doc.html，亲测有效！
有来技术
05-30 2005
Knife4j 生产环境关闭接口文档 doc.html
解决knife4j生产环境（线上）接口暴露
文州的博客
08-01 1433
解决knife4j生产环境（线上）接口暴露
Spring Boot 3和Knife4j的最佳实践 注解对照信息
最新发布
BananaNo2的博客
08-01 1141
在这篇文章中，我们详细介绍了如何在Spring Boot 3项目中整合Knife4j以增强API文档的生成和展示。通过一个具体的项目示例，逐步展示了如何配置pom文件、引入Knife4j依赖、以及在application.yml文件中进行必要的配置。我们还提供了自定义配置的代码示例，展示了如何使用Knife4j配置多个模块和首页描述信息。此外，文章还包含了页面展示信息的截图，方便读者理解最终效果。最后，我们列出了Swagger 2与OpenAPI 3注解的对应关系，帮助开发者快速上手Knife4j。
SpringBoot集成Swagger3，还想来份离线文档？真酷炫
程序新视界
05-08 924
前言 随着项目架构的演化，前后端分离是不可阻挡的趋势。这种模式的协作在实践的过程中经常会遇到的一个问题就是文档。 在《一位CTO告诉我，项目中至少需要这3类文档》一文我们已经描述了文档的重要性，而接口文档便是其中之一，可以说是必不可少的。 但编写接口文档对开发人员来说是一大难题，而且接口还在不断的变化，还要花费精力去维护接口文档的更新。 既然存在痛点，那么必须会出现解决此痛点的产品，这就是Swagger，目前已经更新到Swagger3版本了。如果你还停留在Swagger2，建议升级到Swagger3，整体U
openApi3 规范及knife4j使用
qq_41361668的博客
03-12 3719
OpenApi 规范，swagger3 结合 knife4j 完成接口设计
Knife4j-openapi3简单使用（通俗易懂版）
2203_75372944的博客
07-12 1826
Knife4j-openapi3简单使用（通俗易懂版）
knife4j生产环境资源屏蔽
弹指天下
05-17 6432
knife4j3.0.2生产环境资源屏蔽问题记录
Springboot 3整合Knife4j（Swagger3、OpenApi3）
桃吱咬咬_的博客
07-08 3581
Springboot 3.x项目中使用Knife4j
springboot3.0.11-SNAPSHOT使用knife4j-openapi3所遇见的问题
m0_71683629的博客
09-15 2676
可以访问swagger -ui但是无法访问doc.html，关于在doc.html找不到图标的问题，knife4j-openapi3简单的运用
Springboot集合SwaggerV3(OpenAPI）+ Knife4J 生成接口文档
administrat_c的博客
05-09 1901
Springboot集合SwaggerV3(OpenAPI）+ Knife4J 生成接口文档，内含springboot-actuator与Knife4J冲突，springboot版本不兼容的解决方案。
113-springboot-demo-knife4j-v3.rar
03-07
从上述 Swagger 定义我们不难看出 Swagger 有以下 3 个重要的作用：将项目中所有的接口展现在页面上，这样后端程序员就不需要专门为前端使用者编写专门的接口文档；当接口更新之后，只需要修改代码中的 Swagger 描述...
Knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案
10-09
Knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案。前后端Java代码以及前端Ui模块进行分离,在微服务架构下使用更加灵活。提供专注于Swagger的增强解决方案,不同于只是改善增强前端Ui部分。提供更多灵活的...
springboot3整合knife4j详细版，包会！（不带swagger2玩）
qq_51774011的博客
07-21 4071
springboot3在整合swagger2或者3时均不太好使，而且swagger的默认ui页面真的一言难尽，官方现在推荐使用springdoc-openapi集成接口文档，但是经过测试一些注解个性化文档时存在不好使的情况，而且ui界面依然感觉不好看。本文详细记录了knife4j集成接口文档的详细使用步骤，配置详解以及注解详解。绝对是up亲身测验过的，绝对好用！！！百度了很多内容，踩了很多坑后的整理版。
SpringBoot3.2.0+knife4j-openapi3
qq_33141369的博客
03-26 1388
description("这是基于Knife4j OpenApi3的接口文档").description("SpringBoot基础框架").info(new Info().title("API接口文档")// 开发者联系方式。# 开启Swagger的Basic认证功能,默认是false。4.启动后访问：localhost:8081/doc.html。# knife4j的增强配置，不需要增强可以不配。3.bootstrap.yml配置文件。# Basic认证用户名。# Basic认证密码。
基于springboot3基本使用knife4j-openapi3-jakarta-spring-boot-starter
qq_74947724的博客
05-21 2700
基于springboot使用knife4j完成简单、方便的OpenAPI接口文档开发
springboot 整合 knife4j-openapi3
qq_49444793的博客
05-04 1745
适用于：项目已使用shiro安全认证框架，整合knife4j-openapi3。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

宋冠巡

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

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

余额充值