从零开始编写 SpringBoot RESTful API（附接口文档）

在本教程中，我将一步步指导你如何从零开始构建一个基于 Spring Boot 的 RESTful API，并生成接口文档。Spring Boot 是一个简化 Spring 应用开发的框架，而 RESTful API 是一种基于 HTTP 协议的 Web 服务设计风格。接口文档使用 Swagger 自动生成，确保清晰易用。整个过程分为 7 个步骤，每个步骤都包含代码示例和解释。环境要求：Java 11+、Maven 或 Gradle、IDE（如 IntelliJ IDEA）。

步骤 1: 准备工作（安装依赖）

首先，确保你的开发环境已配置好：

• 安装 Java JDK 11 或更高版本。
• 使用 Spring Initializr（https://start.spring.io/）生成项目骨架，选择以下依赖：
  • Spring Web（用于构建 RESTful API）
  • Spring Data JPA（可选，用于数据库集成）
  • Swagger（用于接口文档）
• 下载生成的项目并导入 IDE。

步骤 2: 创建 Spring Boot 项目

使用 Spring Initializr 创建项目：

• 在网站上选择：
  • Project: Maven 或 Gradle
  • Language: Java
  • Spring Boot 版本：最新稳定版（如 3.1.0）
  • Dependencies: Spring Web, Spring Data JPA, Springdoc OpenAPI（Swagger 替代）
• 点击 "Generate" 下载 ZIP 文件，解压后导入 IDE。

项目结构如下：

src
├── main
│   ├── java
│   │   └── com
│   │       └── example
│   │           └── demo
│   │               ├── DemoApplication.java
│   │               ├── controller
│   │               ├── model
│   │               └── service
│   └── resources
│       └── application.properties

步骤 3: 定义模型类（Model）

创建一个简单的实体类作为 API 的数据模型。例如，定义一个 User 类：

package com.example.demo.model;

import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;

@Entity
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
    private String email;

    // 构造方法、Getter 和 Setter
    public User() {}

    public User(String name, String email) {
        this.name = name;
        this.email = email;
    }

    // Getter 和 Setter 省略，实际代码中需添加
}

步骤 4: 编写 RESTful Controller

创建 Controller 类处理 HTTP 请求。实现基本的 CRUD 操作（创建、读取、更新、删除）。例如，UserController.java：

package com.example.demo.controller;

import com.example.demo.model.User;
import com.example.demo.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/api/users")
public class UserController {

    @Autowired
    private UserService userService;

    // 获取所有用户
    @GetMapping
    public ResponseEntity<List<User>> getAllUsers() {
        return ResponseEntity.ok(userService.findAll());
    }

    // 根据 ID 获取用户
    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        return userService.findById(id)
                .map(ResponseEntity::ok)
                .orElse(ResponseEntity.notFound().build());
    }

    // 创建新用户
    @PostMapping
    public ResponseEntity<User> createUser(@RequestBody User user) {
        return ResponseEntity.ok(userService.save(user));
    }

    // 更新用户
    @PutMapping("/{id}")
    public ResponseEntity<User> updateUser(@PathVariable Long id, @RequestBody User userDetails) {
        return userService.update(id, userDetails)
                .map(ResponseEntity::ok)
                .orElse(ResponseEntity.notFound().build());
    }

    // 删除用户
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        userService.deleteById(id);
        return ResponseEntity.noContent().build();
    }
}

步骤 5: 添加服务层（Service）

服务层处理业务逻辑。创建 UserService.java：

package com.example.demo.service;

import com.example.demo.model.User;
import com.example.demo.repository.UserRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.List;
import java.util.Optional;

@Service
public class UserService {

    @Autowired
    private UserRepository userRepository;

    public List<User> findAll() {
        return userRepository.findAll();
    }

    public Optional<User> findById(Long id) {
        return userRepository.findById(id);
    }

    public User save(User user) {
        return userRepository.save(user);
    }

    public Optional<User> update(Long id, User userDetails) {
        return userRepository.findById(id).map(user -> {
            user.setName(userDetails.getName());
            user.setEmail(userDetails.getEmail());
            return userRepository.save(user);
        });
    }

    public void deleteById(Long id) {
        userRepository.deleteById(id);
    }
}

如果使用数据库，添加 UserRepository.java（接口）：

package com.example.demo.repository;

import com.example.demo.model.User;
import org.springframework.data.jpa.repository.JpaRepository;

public interface UserRepository extends JpaRepository<User, Long> {
}

步骤 6: 集成 Swagger 生成接口文档

Spring Boot 3.x 推荐使用 Springdoc OpenAPI（Swagger UI 的集成）。添加依赖到 pom.xml（Maven）：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version>
</dependency>

在 application.properties 中添加配置：

springdoc.swagger-ui.path=/swagger-ui.html
springdoc.api-docs.path=/api-docs

启动应用后，访问 http://localhost:8080/swagger-ui.html 查看自动生成的接口文档。文档会显示所有 API 端点、请求参数和响应格式，无需手动编写。

步骤 7: 测试 API

使用 Postman 或 curl 测试 API：

• 启动应用：运行 DemoApplication.java。
• 测试端点：
  • 获取所有用户：GET http://localhost:8080/api/users
  • 创建用户：POST http://localhost:8080/api/users，Body 为 JSON：{"name": "Alice", "email": "alice@example.com"}
  • 更新用户：PUT http://localhost:8080/api/users/1，Body 为 JSON：{"name": "Bob", "email": "bob@example.com"}
  • 删除用户：DELETE http://localhost:8080/api/users/1

总结和扩展

恭喜！你已经完成了一个基础的 Spring Boot RESTful API，包括：

• 模型定义、Controller、服务层。
• 自动生成的 Swagger 接口文档（访问 /swagger-ui.html）。
• 完整 CRUD 操作。

进一步扩展建议：

• 添加安全性：集成 Spring Security 实现 JWT 认证。
• 数据库优化：使用 H2 内存数据库或 MySQL。
• 错误处理：添加全局异常处理（如 @ControllerAdvice）。
• 性能监控：集成 Actuator。

完整代码可在 GitHub 仓库参考：[示例仓库链接]。如有问题，随时提问！