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

news2024/11/26 9:00:30

版本：

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

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.coloradmin.cn/o/2196051.html

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈，一经查实，立即删除！

相关文章

笔试强训day33

笔试强训day33

跳台阶扩展问题 一只青蛙一次可以跳上1级台阶&#xff0c;也可以跳上2级……它也可以跳上n级。求该青蛙跳上一个n级的台阶(n为正整数)总共有多少种跳法。 数据范围&#xff1a;1≤n≤201≤n≤20 进阶&#xff1a;空间复杂度 O(1)O(1) &#xff0c; 时间复杂度 O(1)O(1) 输入…
阅读更多...
【EXCEL数据处理】000017 案例 保姆级教程，附多个操作案例。EXCEL Match和Index函数。

【EXCEL数据处理】000017 案例 保姆级教程，附多个操作案例。EXCEL Match和Index函数。

前言&#xff1a;哈喽&#xff0c;大家好&#xff0c;今天给大家分享一篇文章&#xff01;创作不易&#xff0c;如果能帮助到大家或者给大家一些灵感和启发&#xff0c;欢迎收藏关注哦 &#x1f495; 目录 【EXCEL数据处理】000017 案例 保姆级教程&#xff0c;附多个操作案例。…
阅读更多...
MYSQL 事物隔离级别的区别与现象

MYSQL 事物隔离级别的区别与现象

事物的ACID属性本章不再赘述&#xff0c;本章主要描述事物的隔离级别及隔离级别导致的现象&#xff0c;日常工作中该如何选择MYSQL的隔离级别。 MYSQL事物的隔离级别及各隔离级别存在的问题如下&#xff1a; 隔离级别/问题脏读不可重复读幻读读未提交(Read-Uncommitted)✅✅✅…
阅读更多...
JS 入门

JS 入门

文章目录 JS 入门一、JS 概述1、JS 特点2、JS 组成3、JS 初体验4、HTML引入JS 二、JS 基础语法1、变量声明2、基本数据类型3、引用数据类型1&#xff09;数组2&#xff09;对象3&#xff09;函数4&#xff09;null 4、运算符5、条件判断6、循环语句 三、JS 函数0、JS 函数特点1…
阅读更多...
知识图谱入门——11：构建动态图谱渲染应用：Vue3与Neo4j的集成与实践

知识图谱入门——11：构建动态图谱渲染应用：Vue3与Neo4j的集成与实践

在知识图谱与大数据技术领域&#xff0c;构建动态图谱是一项非常重要的任务。这篇博客将带你深入了解如何利用Vue.js、D3.js以及Neo4j&#xff0c;开发一个能够实时渲染图谱节点和关系的应用。我们将从零开始&#xff0c;介绍如何搭建开发环境、安装依赖、与Neo4j数据库交互、到…
阅读更多...
获取yolov8自带的数据集并开始训练

获取yolov8自带的数据集并开始训练

今天小编带大家学习一下YOLOv8 配置文件&#xff0c;用来定义不同数据集的参数和配置。这些文件包含了关于每个数据集的路径、类别数、类别标签等信息&#xff0c;帮助模型正确地加载和解析数据集&#xff0c;以便进行训练和推理。 具体来说&#xff0c;这些 YAML 文件的作用如…
阅读更多...
各省份技术市场成交额数据（2001-2022年）

各省份技术市场成交额数据（2001-2022年）

数据名称&#xff1a;各省份技术市场成交额数据数据年份&#xff1a;2001-2022年数据来源&#xff1a;《中国统计年鉴》字段说明&#xff1a; id&#xff1a;数据条目编号省份&#xff1a;中国各省份年份&#xff1a;2001-2022年技术市场成交额(万元)&#xff1a;表示该省份在特…
阅读更多...
基于Springboot vue的流浪狗领养管理系统设计与实现

基于Springboot vue的流浪狗领养管理系统设计与实现

博主介绍&#xff1a;专注于Java&#xff08;springboot ssm 等开发框架&#xff09; vue .net php python(flask Django) 小程序 等诸多技术领域和毕业项目实战、企业信息化系统建设&#xff0c;从业十五余年开发设计教学工作☆☆☆ 精彩专栏推荐订阅☆☆☆☆☆不然下次找…
阅读更多...
Win10 IDEA连接虚拟机中的Hadoop（HDFS）

Win10 IDEA连接虚拟机中的Hadoop（HDFS）

获取虚拟机的ip 虚拟机终端输入 ip a关闭虚拟机防火墙 sudo ufw disable修改Hadoop的core-site.xml文件 将localhost修改为虚拟机局域网IP # 位置可能不一样&#xff0c;和Hadoop安装位置有关 cd /usr/local/hadoop/etc/hadoop vim core-site.xmlIDEA 连接 创建Maven项目…
阅读更多...
软考系统分析师知识点四：操作系统基本原理

软考系统分析师知识点四：操作系统基本原理

前言 今年报考了11月份的软考高级&#xff1a;系统分析师。 考试时间为&#xff1a;11月9日。 倒计时&#xff1a;33天。 目标&#xff1a;优先应试&#xff0c;其次学习&#xff0c;再次实践。 复习计划第一阶段&#xff1a;扫平基础知识点&#xff0c;仅抽取有用信息&am…
阅读更多...
如何删除或减少pagefile.sys？

如何删除或减少pagefile.sys？

您是否曾在计算机上遇到过一个名为 pagefile.sys 的超大文件&#xff1f; 许多 Windows 用户想知道 pagefile.sys 的用途以及如何在不影响系统性能的情况下有效地管理它。 本文将帮助您了解 pagefile.sys 是什么、它为什么会变大以及如何安全地管理它的大小。 什么是 pagefi…
阅读更多...
基于UDP协议的网络通信

基于UDP协议的网络通信

和TCP协议不同的是&#xff0c;UDP协议不需要进行稳定的连接即可直接对数据进行收发&#xff0c;即面向非连接的。所以UDP的应用场景在音视频流传输、在线游戏以及网络聊天室等实时传输需求大的背景。因为不需要建立连接&#xff0c;UDP的网络编程模型就比TCP简单许多。 接收端…
阅读更多...
Qt - ui界面点击加载一段时间后闪退

Qt - ui界面点击加载一段时间后闪退

Qt - ui界面点击加载一段时间后闪退 解决方案&#xff1a; 该路径下删除 widgetbox6.8.xml 文件即可&#xff0c;然后重新打开 QT 就可以成功打开 UI 界面了
阅读更多...
【2024最新】基于springboot+vue的交流互动系统lw+ppt

【2024最新】基于springboot+vue的交流互动系统lw+ppt

作者&#xff1a;计算机搬砖家 开发技术&#xff1a;SpringBoot、php、Python、小程序、SSM、Vue、MySQL、JSP、ElementUI等&#xff0c;“文末源码”。 专栏推荐&#xff1a;SpringBoot项目源码、Vue项目源码、SSM项目源码、微信小程序源码 精品专栏&#xff1a;Java精选实战项…
阅读更多...
Spring Boot框架下的足球青训俱乐部管理

Spring Boot框架下的足球青训俱乐部管理

2 相关技术简介 2.1 Java技术 Java是一门伟大的纯面向对象的编程语言和编程语言。同时&#xff0c;它还是Java语言从嵌入式开发到企业级开发的平台。Java凭借其一次编译&#xff0c;任何地方执行的优点&#xff0c;使得盛行的web应用程序有大量的Java编译&#xff0c;很好地支…
阅读更多...
【AIGC】ChatGPT提示词Prompt高效编写模式：结构化Prompt、提示词生成器与单样本/少样本提示

【AIGC】ChatGPT提示词Prompt高效编写模式：结构化Prompt、提示词生成器与单样本/少样本提示

博客主页&#xff1a; [小ᶻZ࿆] 本文专栏: AIGC | ChatGPT 文章目录 &#x1f4af;前言&#x1f4af;结构化Prompt (Structured Prompt)组成元素应用实例优势结论 &#x1f4af;提示词生成器 (Prompt Creator)如何工作应用实例优势结论 &#x1f4af;单样本/少样本提示 (O…
阅读更多...
LeetCode讲解篇之746. 使用最小花费爬楼梯

LeetCode讲解篇之746. 使用最小花费爬楼梯

文章目录 题目描述题解思路题解代码题目链接 题目描述 题解思路 爬到第i层的最小花费 min(爬到第i - 1层的最小花费 从第i - 1层向上爬的花费, 爬到第i - 2层的最小花费 从第i - 2层向上爬的花费) 设f[i]为爬到第i层的最小花费 则f[i] min(f[i - 1] cost[i - 1], f[i -…
阅读更多...
红外变电站分割数据集，标注为json格式，总共有5类，避雷器（289张），绝缘子（919张），电流互感器（413张），套管（161张），电压互感器（153张）

红外变电站分割数据集，标注为json格式，总共有5类，避雷器（289张），绝缘子（919张），电流互感器（413张），套管（161张），电压互感器（153张）

红外变电站分割数据集&#xff0c;标注为json格式&#xff0c;总共有5类 避雷器&#xff08;289张&#xff09;&#xff0c;绝缘子&#xff08;919张&#xff09;&#xff0c;电流互感器&#xff08;413张&#xff09;&#xff0c;套管&#xff08;161张&#xff09;&#xff0…
阅读更多...
IDEA：增加类注释模板和方法注释模板

IDEA：增加类注释模板和方法注释模板

文章目录 概要配置类注释模板配置方法模版 概要 配置类注释和方法注释 配置类注释模板 点击setting->Editor->File and Code Templates&#xff0c;然后找到Class&#xff0c;如下图&#xff1a; 注意勾掉Reformat according to style&#xff0c;否则会格式化。 注…
阅读更多...
Revisiting Graph-Based Fraud Detection in Sight of Heterophily and Spectrum

Revisiting Graph-Based Fraud Detection in Sight of Heterophily and Spectrum

AAAI24 推荐指数&#xff1a; #paper/⭐ 领域&#xff1a;异常检测 摘要 这篇文章是关于一种新型的基于图神经网络&#xff08;GNN&#xff09;的欺诈检测方法&#xff0c;称为SEC-GFD&#xff08;Spectrum-Enhanced and Environment-Constrainted Graph Fraud Detector&…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023