# Pinia-openapi-server **Repository Path**: luote996_admin/pinia-openapi ## Basic Information - **Project Name**: Pinia-openapi-server - **Description**: Pinia-openapi的后端服务 - **Primary Language**: Java - **License**: MulanPSL-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2025-11-23 - **Last Updated**: 2025-12-02 ## Categories & Tags **Categories**: Uncategorized **Tags**: 教学项目, pinia教学项目, SpringBoot, Swagger ## README # SwaggerTest 后端项目 基于 Spring Boot + MyBatis + MySQL 的后端服务，使用 Knife4j 提供 OpenAPI 3 文档。 **忒科技** ## 项目地址 **后端项目仓库**：[https://gitee.com/luote996_admin/pinia-openapi](https://gitee.com/luote996_admin/pinia-openapi) **前端项目仓库**：[https://gitee.com/luote996_admin/pinia-openapi-vue](https://gitee.com/luote996_admin/pinia-openapi-vue) ## 联调地址 以下地址用于前后端联调，开发时请确保服务已启动： - **后端服务地址**：`http://localhost:8080` - **前端开发地址**：`http://localhost:5173` - **Knife4j 接口文档**：`http://localhost:8080/doc.html` - **OpenAPI 文档地址**：`http://localhost:8080/v3/api-docs` - **OpenAPI JSON 地址**：`http://localhost:8080/v3/api-docs.json` ## 项目简介 本项目是一个 Spring Boot 后端服务，提供 RESTful API 接口，并通过 Knife4j 生成 OpenAPI 3 规范文档。前端可以通过 OpenAPI 文档自动生成 API 调用代码，实现前后端的无缝对接。 ## 技术栈 - **框架**：Spring Boot 3.4.11 - **持久层**：MyBatis 3.0.3 - **数据库**：MySQL - **文档工具**：Knife4j 4.4.0（OpenAPI 3） - **Java 版本**：Java 17 - **工具库**：Lombok ## 项目结构 ``` swaggertest/ ├── src/ │ ├── main/ │ │ ├── java/ │ │ │ └── org/qt/swaggertest/ │ │ │ ├── config/ # 配置类 │ │ │ │ └── CorsConfig.java # 跨域配置 │ │ │ ├── controller/ # 控制器层 │ │ │ │ ├── admin/ # 管理员相关接口 │ │ │ │ └── user/ # 用户相关接口 │ │ │ ├── service/ # 服务层 │ │ │ │ ├── impl/ # 服务实现类 │ │ │ │ ├── AdminService.java │ │ │ │ └── UserService.java │ │ │ ├── mapper/ # 数据访问层 │ │ │ │ └── UserMapper.java │ │ │ ├── pojo/ # 实体类 │ │ │ │ ├── dto/ # 数据传输对象 │ │ │ │ ├── vo/ # 视图对象 │ │ │ │ └── entity/ # 实体类 │ │ │ └── SwaggertestApplication.java # 启动类 │ │ └── resources/ │ │ ├── application.yml # 应用配置 │ │ ├── mapper/ # MyBatis XML 映射文件 │ │ └── sql/ # SQL 脚本 │ └── test/ # 测试代码 └── pom.xml # Maven 依赖配置 ``` ## 环境要求 - JDK 17 或更高版本 - Maven 3.6 或更高版本 - MySQL 5.7 或更高版本 ## 快速开始 ### 1. 创建数据库 在 MySQL 中创建数据库： ```sql CREATE DATABASE `openapi——pinia` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; ``` ### 2. 导入数据库脚本 执行 `src/main/resources/sql/user.sql` 中的 SQL 脚本，创建数据表。 ### 3. 修改数据库配置 编辑 `src/main/resources/application.yml`，修改数据库连接信息： ```yaml spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/openapi——pinia?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai username: root password: 123456 ``` 根据实际情况修改数据库地址、用户名和密码。 ### 4. 启动应用 #### 方式一：使用 Maven ```bash mvn spring-boot:run ``` #### 方式二：使用 IDE 直接运行 `SwaggertestApplication.java` 的 `main` 方法。 #### 方式三：打包后运行 ```bash mvn clean package java -jar target/swaggertest-0.0.1-SNAPSHOT.jar ``` ### 5. 访问接口文档 启动后访问以下地址： - **Knife4j 文档地址**：`http://localhost:8080/doc.html` - **OpenAPI 文档地址**：`http://localhost:8080/v3/api-docs` - **OpenAPI JSON**：`http://localhost:8080/v3/api-docs.json` ## 核心特性 ### 1. OpenAPI 3 文档 使用 Knife4j 自动生成 OpenAPI 3 规范的接口文档，前端可以通过该文档自动生成 API 调用代码。 ### 2. 统一响应格式 接口返回统一的数据格式，便于前端处理。 ### 3. 跨域支持 已配置跨域（CORS），支持前后端分离部署。 ### 4. MyBatis 集成 使用 MyBatis 作为持久层框架，支持 XML 和注解两种方式。 ## 接口开发规范 ### Controller 层 使用 `@Tag` 和 `@Operation` 注解描述接口： ```java @Tag(name = "用户管理", description = "用户相关接口") @RestController @RequestMapping("/user") public class UserController { @Operation(summary = "获取用户列表", description = "获取所有用户信息") @GetMapping public ResponseEntity> getAllUsers() { // 业务逻辑 } } ``` ### Service 层 实现业务逻辑，使用 `@Service` 注解： ```java @Service public class UserServiceImpl implements UserService { // 业务实现 } ``` ### Mapper 层 使用 `@Mapper` 注解或 MyBatis XML 映射文件： ```java @Mapper public interface UserMapper { List selectAll(); } ``` ### 数据传输对象 - **DTO（Data Transfer Object）**：用于接收前端请求数据 - **VO（View Object）**：用于返回给前端的数据 - **Entity**：数据库实体类 ## 配置说明 ### 应用配置 主要配置位于 `src/main/resources/application.yml`： ```yaml spring: application: name: swaggertest datasource: # 数据库配置 mvc: pathmatch: matching-strategy: ant_path_matcher # 支持 Swagger3 mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: org.qt.swaggertest.pojo.entity configuration: map-underscore-to-camel-case: true knife4j: enable: true openapi: title: "接口文档" version: 1.0 ``` ### 跨域配置 跨域配置位于 `src/main/java/org/qt/swaggertest/config/CorsConfig.java`，允许前端跨域访问。 ## 构建部署 ### 构建 ```bash mvn clean package ``` 构建产物位于 `target/swaggertest-0.0.1-SNAPSHOT.jar` ### 运行 ```bash java -jar target/swaggertest-0.0.1-SNAPSHOT.jar ``` ### 生产环境部署 1. 修改 `application.yml` 中的数据库配置为生产环境配置 2. 可以创建 `application-prod.yml` 作为生产环境配置文件 3. 运行构建命令打包 4. 部署 JAR 包到服务器 ## 测试 运行测试用例： ```bash mvn test ``` ## 常见问题 ### Q1: 如何更新 OpenAPI 文档？ A: 确保 Controller 中的注解完整（`@Tag`、`@Operation`、`@Parameter` 等），重启应用后文档会自动更新。 ### Q2: OpenAPI 文档地址是什么？ A: 启动后访问 `http://localhost:8080/doc.html`（Knife4j UI）或 `http://localhost:8080/v3/api-docs`（OpenAPI JSON）。 ### Q3: 如何配置跨域？ A: 跨域配置在 `CorsConfig.java` 中，已配置允许所有来源，生产环境建议修改为具体的前端地址。 ### Q4: MyBatis 映射文件在哪里？ A: MyBatis XML 映射文件位于 `src/main/resources/mapper/` 目录下。 ## 开发规范 1. Controller 层只负责接收请求和返回响应，不包含业务逻辑 2. 业务逻辑统一在 Service 层实现 3. 数据库操作统一在 Mapper 层实现 4. 使用 DTO 接收请求数据，使用 VO 返回响应数据 5. 接口必须添加完整的 OpenAPI 注解，便于生成文档 ## 关于 本项目由 **忒科技** 开发维护。 **后端项目地址**：[https://gitee.com/luote996_admin/pinia-openapi](https://gitee.com/luote996_admin/pinia-openapi) **前端项目地址**：[https://gitee.com/luote996_admin/pinia-openapi-vue](https://gitee.com/luote996_admin/pinia-openapi-vue)