用户模块——升级swagger文档更漂亮

引言

        在开发 Web 应用时，前后端需要通过接口进行数据交互。而 Swagger 就是用来自动生成接口文档的，它能让前端直观地查看和测试 API，提高开发效率。

        不过，Swagger 默认的界面比较简陋，不够美观和易用。为了解决这个问题，我们可以引入 Knife4j，它是对 Swagger 进行了增强的工具，让接口文档更直观、更友好。

        本文将带你一步步优化 Swagger 文档，让它更美观、更易用，同时兼顾权限控制和接口管理，帮助你快速搭建一个更专业的 API 文档。

引入 Knife4j

        默认情况下，Swagger 提供的 API 文档界面比较简单，虽然能用，但不够美观，体验也一般。Knife4j 就是一个用来增强 Swagger 的工具，它能让接口文档变得更漂亮，还能增加更多实用功能，比如分组显示、接口调试等。

1. 添加 Knife4j 依赖

首先，我们需要在 pom.xml 里添加 Knife4j 的依赖：

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>4.0.0</version>  <!-- 这里可以使用最新版本 -->
</dependency>

2. 解决 Swagger 2.6 版本的 Bug

有些版本的 Swagger（比如 2.6）和 Knife4j 不兼容，可能会导致页面打不开。解决办法有两个：

  • 方案 1：降低 Spring Boot 版本（不推荐，可能影响其他依赖）
  • 方案 2：在 application.yml 里添加兼容性配置（推荐）：
spring:mvc:pathmatch:matching-strategy: ant_path_matcher

这样，我们就可以正常使用 Knife4j 了。

3. 访问接口文档

启动项目后，在浏览器里输入：

http://localhost:8080/doc.html

        你会发现，Swagger 的界面变得更漂亮了，还多了一些方便的功能，比如接口分组、参数示例等。至此，Knife4j 就成功引入了！

Swagger 配置

        Swagger 默认可以扫描接口并生成文档，但如果我们想要更好地管理 API，比如 自定义文档信息、分组、隐藏某些接口，就需要自己配置 Swagger。

1. 创建 Swagger 配置类

在 config 目录下，新建 SwaggerConfig.java，用来管理 Swagger 的基础配置：

@Configuration
@EnableOpenApi  // 启用 Swagger
public class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.OAS_30)  // 选择 OpenAPI 3.0 规范.apiInfo(apiInfo())  // 设置文档信息.select().apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 扫描指定包.paths(PathSelectors.any())  // 允许所有路径.build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("用户模块 API 文档")  // 文档标题.description("这是用户相关接口的文档，包含用户信息等")  // 简要说明.version("1.0")  // 版本号.contact(new Contact("开发者", "https://example.com", "email@example.com"))  // 联系方式.build();}
}

2. 主要配置项解析

  • @EnableOpenApi：开启 Swagger 功能。
  • Docket：核心配置类，用于定义 API 文档规则。
  • .apiInfo(apiInfo())：设置文档基本信息，比如 标题、描述、版本号 等。
  • .apis(RequestHandlerSelectors.basePackage("com.example.controller"))：告诉 Swagger 只扫描 controller 包下的接口，避免扫描不必要的类。
  • .paths(PathSelectors.any())：表示所有的 API 都会被扫描并展示。

3. 配置完成后如何访问？

启动项目后，在浏览器访问：

http://localhost:8080/doc.html

你会看到 Swagger 自动生成的 API 文档，所有的用户接口都在里面！

        至此，我们的 Swagger 配置已经完成，不仅能自动生成文档，还能自定义 API 信息，让接口管理更加清晰明了。

接口文档访问与使用

        Swagger 配置好之后，我们就可以访问接口文档，查看 API 详情，并直接测试接口请求。下面带你一步步体验 Swagger 的使用。

1. 访问接口文档

启动项目后，在浏览器地址栏输入：

http://localhost:8080/doc.html

如果一切正常，你会看到一个 美观的接口文档页面，这就是 Knife4j 给 Swagger 生成的 API 界面。

2. 了解接口文档内容

Swagger 文档页面主要有以下几个部分：

  • 左侧菜单：显示所有分组的 API，比如“用户信息接口”。
  • 接口列表：展示当前分组下所有的 API，包括 请求方式（GET、POST等）、URL 路径、接口描述。
  • 接口详情：点开某个接口，就能看到 请求参数 和 响应数据格式。

3. 测试接口请求

Swagger 提供了 在线调试 功能，让你可以不用写代码，直接测试接口是否正常工作。
以 获取用户信息 接口为例，操作如下：

  1. 找到 用户信息接口（GET /user/info）。
  2. 点击 “调试” 按钮。
  3. 点击 “发送请求”，查看接口返回的数据。

如果接口正常，你会看到类似下面的 JSON 响应：

{"id": 1,"name": "张三","avatar": "https://example.com/avatar.jpg","sex": "男"
}

4. 控制接口访问权限

有时候，我们需要控制接口的访问权限，比如：

  • 公开接口（public）：所有用户都能访问。
  • 私有接口（private）：需要登录才能访问。

在 @GetMapping 里，我们可以直接设置路径，比如：

@GetMapping("/info/public")  // 公开接口
@GetMapping("/info/private")  // 私有接口，需要拦截处理

对于私有接口，我们可以在拦截器或者 @PreAuthorize 里加权限校验，让未授权用户无法访问。

        到这里，你已经掌握了 Swagger 文档的访问与使用，可以随时查看 API，并在线测试接口，让前后端协作更高效！

权限控制与拦截

在实际项目中，并不是所有接口都可以随意访问，比如：

  • 登录接口：所有用户都能访问（公开接口）。
  • 获取个人信息接口：必须登录后才能访问（私有接口）。
  • 管理后台接口：只有管理员才能访问（管理员权限）。

为了实现 权限控制，我们需要做两件事：

  1. 标记接口权限类型，比如 公开（public）、私有（private）。
  2. 拦截未授权请求，防止非法访问。

1. 使用 @PreAuthorize 进行权限控制

        Spring Security 提供了 @PreAuthorize 注解，可以用来 控制某个接口的访问权限。
示例代码如下：

@RestController
@RequestMapping("/user")
public class UserController {@GetMapping("/info/public")public String publicInfo() {return "这是一个公开接口，所有人都能访问";}@GetMapping("/info/private")@PreAuthorize("isAuthenticated()")  // 需要登录public String privateInfo() {return "这是一个私有接口，必须登录才能访问";}@GetMapping("/info/admin")@PreAuthorize("hasRole('ADMIN')")  // 需要管理员权限public String adminInfo() {return "这是管理员接口，只有管理员能访问";}
}

🔹 解释一下上面的代码：

  • @PreAuthorize("isAuthenticated()")：表示 必须登录 才能访问。
  • @PreAuthorize("hasRole('ADMIN')")：表示 只有管理员 才能访问。

2. 拦截未授权请求

        如果用户访问了 需要权限的接口，但没有登录或权限不足，就会返回 403 Forbidden，表示 无权访问。

可以在 全局异常处理 里，统一处理未授权异常，返回友好的提示信息。

@RestControllerAdvice
public class GlobalExceptionHandler {@ExceptionHandler(AccessDeniedException.class)public ResponseEntity<String> handleAccessDenied(AccessDeniedException e) {return ResponseEntity.status(HttpStatus.FORBIDDEN).body("你没有权限访问这个接口");}
}

这样，如果用户 没有权限，就会返回 “你没有权限访问这个接口”，而不是默认的 错误页面。

3. 使用拦截器拦截未登录请求

如果你的项目没有使用 Spring Security，也可以使用 拦截器 来手动拦截未登录用户。

步骤：

  1. 创建拦截器（AuthInterceptor.java），检查用户是否登录。
  2. 注册拦截器，拦截指定的 API 路径。
@Component
public class AuthInterceptor implements HandlerInterceptor {@Overridepublic boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {HttpSession session = request.getSession();if (session.getAttribute("user") == null) {response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);response.getWriter().write("请先登录");return false;}return true;}
}

然后，在 WebMvcConfig 里 注册拦截器，让它拦截 /user/info/private 这种私有接口。

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {@Overridepublic void addInterceptors(InterceptorRegistry registry) {registry.addInterceptor(new AuthInterceptor()).addPathPatterns("/user/info/private");  // 只拦截私有接口}
}

4. 访问权限控制的效果

  1. 未登录访问 /user/info/private，返回 “请先登录”。
  2. 普通用户访问 /user/info/admin，返回 “你没有权限访问这个接口”。
  3. 管理员访问 /user/info/admin，正常返回数据。

这样，我们就成功实现了 权限控制 和 未授权拦截，确保接口不会被随意访问！

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

如若内容造成侵权/违法违规/事实不符，请联系长河编程网进行投诉反馈email:809451989@qq.com，一经查实，立即删除！

相关文章

wordpress-网站百宝箱插件

wordpress-网站百宝箱插件

含置顶,网页宠物, 哀悼, 禁止复制, 禁止查看源码, 弹幕, WP优化,媒体分类,预加载,定时发布,在线客服, 留言板, 手机客服, 网站背景, 公告, 跑马灯, 水印, 分享, 打赏, 海报图, 广告,数据库管理,图片加载特效。等综合功能插件
阅读更多...
Git 钩子：特定操作脚本

Git 钩子：特定操作脚本

Git 钩子 在特定 Git 操作发生时自动触发的脚本&#xff1b; 可以从提交规范、代码质量、自动化流程、分支管理、安全性检查等多个方面进行配置&#xff0c;帮助团队提高开发效率和代码质量&#xff1b; 本地 记录提交检验 commit-msg 修改&#xff1a;\test\.git\hooks\c…
阅读更多...
职坐标：互联网行业职业发展路径解析

职坐标：互联网行业职业发展路径解析

内容概要 当前&#xff0c;互联网行业正以指数级速度重塑全球产业格局。数据显示&#xff0c;我国互联网市场规模在2019年上半年实现17.9%的同比增速&#xff0c;而随着工业互联网、5G等前沿技术的加速落地&#xff0c;这一增长趋势仍在强化。工信部近期发布的《新型信息基础设…
阅读更多...
红数码影视(RED Digital Cinema)存储卡格式化后的恢复方法

红数码影视(RED Digital Cinema)存储卡格式化后的恢复方法

红数码影视(RED Digital Cinema)的摄像机可以生成两种RAW级高清视频文件&#xff0c;一种是R3D&#xff0c;一种是MOV。其中MOV属于苹果(apple)公司的QT视频封装结构&#xff0c;使用的视频编码是Apple ProRes;而R3D则是RED公司自创的RAW视频文件&#xff0c;这种文件解码需要使…
阅读更多...
Gitee上库常用git命令

Gitee上库常用git命令

Gitee上库常用git命令 1、Fork 项目2、个人仓库修改3、追加提交4、创建PR5、多笔commit合一 1、Fork 项目 2、个人仓库修改 git add . // -s 表示自动添加邮箱签名信息&#xff0c;-m表示其后跟随commit描述 git commit -sm “add transition freeze” git push origin [目标…
阅读更多...
阿里开源的免费数据集成工具——DataX

阿里开源的免费数据集成工具——DataX

企业里真实的数据流转是什么样子的呢&#xff1f; 左侧描述了一个企业真实的样子&#xff0c;我们总是需要把数据从一个地方搬到另一个地方&#xff0c;最后就是搬来搬去搬成了一张张解不开的网。 右侧则表达了使用DataX为中心实现数据的同步。 什么是DataX DataX是一个异构…
阅读更多...
SpringBoot学习笔记（主）

SpringBoot学习笔记（主）

文章目录 SpringBoot概述自动装配&#xff08;部分&#xff09;概述原理简述相关解释源码位置EnableAutoConfigurationAutoConfigurationImportSelector 配置文件yaml语法单双引号列表多行字符串 配置文件的位置和加载顺序配置文件取值运行jar包 Springboot整合springmvc自动管…
阅读更多...
python多线程和多进程的区别有哪些

python多线程和多进程的区别有哪些

python多线程和多进程的区别有七种&#xff1a; 1、多线程可以共享全局变量&#xff0c;多进程不能。 2、多线程中&#xff0c;所有子线程的进程号相同&#xff1b;多进程中&#xff0c;不同的子进程进程号不同。 3、线程共享内存空间&#xff1b;进程的内存是独立的。 4、同一…
阅读更多...
docker 安装部署 canal

docker 安装部署 canal

1 mysql 安装 1.1 拉取镜像 docker pull mysql:8.4.41.2 创建挂载目录 mkdir -p /user/lzl/tool/docker/mysql/mysql_8.4.4/home/confmkdir -p /user/lzl/tool/docker/mysql/mysql_8.4.4/home/datamkdir -p /user/lzl/tool/docker/mysql/mysql_8.4.4/home/log1.3 编辑配置文…
阅读更多...
基于SpringBoot的图书借阅小程序+LW参考示例

基于SpringBoot的图书借阅小程序+LW参考示例

系列文章目录 1.基于SSM的洗衣房管理系统原生微信小程序LW参考示例 2.基于SpringBoot的宠物摄影网站管理系统LW参考示例 3.基于SpringBootVue的企业人事管理系统LW参考示例 4.基于SSM的高校实验室管理系统LW参考示例 5.基于SpringBoot的二手数码回收系统原生微信小程序LW参考示…
阅读更多...
ElasticSearch快速入门--实现分词搜索

ElasticSearch快速入门--实现分词搜索

分词题目搜索 使用Elasticsearch实现题目数据的存储和分词搜索&#xff0c;需要将数据库的数据同步到 Elasticsearch。 ElasticSearch入门 ElasticSearch&#xff08;简称ES&#xff09;是一个开源的分布式搜索和数据分析引擎&#xff0c;用Java开发并且是当前最流行的开源的…
阅读更多...
debug - 安装.msi时，为所有用户安装程序

debug - 安装.msi时，为所有用户安装程序

文章目录 debug - 安装.msi时&#xff0c;为所有用户安装程序概述笔记试试在目标.msi后面直接加参数的测试 备注备注END debug - 安装.msi时&#xff0c;为所有用户安装程序 概述 为了测试&#xff0c;装了一个test.msi. 安装时&#xff0c;只有安装路径的选择&#xff0c;没…
阅读更多...
Skyeye 云智能制造办公系统 VUE 版本 v3.15.14 发布

Skyeye 云智能制造办公系统 VUE 版本 v3.15.14 发布

Skyeye 云智能制造&#xff0c;采用 Springboot winUI 的低代码平台、移动端采用 UNI-APP。包含 30 多个应用模块、50 多种电子流程&#xff0c;CRM、PM、ERP、MES、ADM、EHR、笔记、知识库、项目、门店、商城、财务、多班次考勤、薪资、招聘、云售后、论坛、公告、问卷、报表…
阅读更多...
深度学习PyTorch之动态计算图可视化 - 使用 torchviz 生成计算图

深度学习PyTorch之动态计算图可视化 - 使用 torchviz 生成计算图

序号系列文章1深度学习训练中GPU内存管理2深度学习PyTorch之数据加载DataLoader3深度学习 PyTorch 中 18 种数据增强策略与实现4深度学习pytorch之简单方法自定义9类卷积即插即用5深度学习PyTorch之13种模型精度评估公式及调用方法6深度学习pytorch之4种归一化方法&#xff08;…
阅读更多...
ZW3D二次开发_非模板表单_输入框类控件_逐字符回调

ZW3D二次开发_非模板表单_输入框类控件_逐字符回调

ZW3D的非模板表单的控件中有一些输入框类的控件&#xff0c;比如“ZsCc::LineEditBtn”,"ZsCc::LineEditEx"等&#xff0c;按照“ZW3D二次开发_非模板表单_控件_添加回调-CSDN博客”介绍的方法添加函数命令时&#xff0c;发现输入框在用户输入字符时不能动态地触发回…
阅读更多...
Mysql--日志（错误日志、二进制日志、查询日志、慢查询日志）

Mysql--日志（错误日志、二进制日志、查询日志、慢查询日志）

四种日志对比总结 日志类型作用记录内容特点常见用途错误日志记录 MySQL 运行过程中的错误、警告及启动、关闭信息MySQL 系统错误、故障信息、警告等较少占用磁盘空间故障排查、系统监控二进制日志记录所有更改数据库数据的操作及事务执行情况DML、DDL 操作&#xff0c;不记录…
阅读更多...
AI对软件工程（software engineering）的影响在哪些方面？

AI对软件工程（software engineering）的影响在哪些方面？

AI对软件工程&#xff08;software engineering&#xff09;的影响是全方位且深远的&#xff0c;它不仅改变了传统开发流程&#xff0c;还重新定义了工程师的角色和软件系统的构建方式。以下是AI影响软件工程的核心维度&#xff1a; 一、开发流程的智能化重构 需求工程革命 • …
阅读更多...
ElementPlus 快速入门

ElementPlus 快速入门

目录 前言 为什么要学习 ElementPlus&#xff1f; 正文 步骤 1 创建 一个工程化的vue 项目 ​2 安装 element-Plus :Form 表单 | Element Plus 1 点击 当前界面的指南 2 点击左边菜单栏上的安装&#xff0c;选择包管理器 3 运行该命令 demo(案例1 &#xff09; 步骤 …
阅读更多...
stable diffusion本地安装

stable diffusion本地安装

1. 基本环境准备 安装conda 环境 pytorch基础学习-CSDN博客 创建虚拟环境&#xff1a; conda create -n sd python3.10 一定要指定用3.10&#xff0c;过高的版本会提示错误&#xff1a; 激活启用环境&#xff1a; conda activate sd 设置pip国内镜像源&#xff1a; pip conf…
阅读更多...
使用 Go 构建 MCP Server

使用 Go 构建 MCP Server

一个互联网技术玩家&#xff0c;一个爱聊技术的家伙。在工作和学习中不断思考&#xff0c;把这些思考总结出来&#xff0c;并分享&#xff0c;和大家一起交流进步。 一、MCP 介绍 1. 基本介绍 MCP&#xff08;Model Context Protocol&#xff0c;模型上下文协议&#xff09;是…
阅读更多...
最新文章
推荐文章

Copyright @ 2022~2023