当前位置：首页 > wzjs >正文

电子创意设计网站合肥html5网站建设

wzjs 2025/9/23 10:39:35

电子创意设计网站,合肥html5网站建设,国内wordpress主题免费,开发公司简介范文大全引言在开发 Web 应用时，前后端需要通过接口进行数据交互。而 Swagger 就是用来自动生成接口文档的，它能让前端直观地查看和测试 API，提高开发效率。不过，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 提供了 在线调试 功能，让你可以不用写代码，直接测试接口是否正常工作。
以 获取用户信息 接口为例，操作如下：

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

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

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

4. 控制接口访问权限

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

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

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

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

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

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

权限控制与拦截

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

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

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

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

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，也可以使用 拦截器 来手动拦截未登录用户。

步骤：

创建拦截器（AuthInterceptor.java），检查用户是否登录。
注册拦截器，拦截指定的 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");  // 只拦截私有接口}
}