【java】[工具Swagger]-------- Spring Boot 3 集成 Swagger 3 完整指南

Spring Boot 3 集成 Swagger 3 完整指南

Swagger（现更名为OpenAPI）是一个用于设计、构建和文档化API的强大工具。在Spring Boot 3中集成Swagger 3（OpenAPI 3.0）可以帮助我们自动生成API文档，方便前后端开发人员协作。

一、依赖配置

首先，在pom.xml中添加SpringDoc OpenAPI依赖（Swagger 3的官方实现）：

<!-- SpringDoc OpenAPI 核心依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version>
</dependency>

这个依赖包含了：

• OpenAPI 3.0规范的实现
• Swagger UI界面
• 与Spring Boot 3的自动配置

二、基本配置

创建Swagger配置类，自定义API文档信息：

package com.example.demo.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 io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Spring Boot 3 API 文档")
                        .version("1.0.0")
                        .description("这是一个使用Spring Boot 3和Swagger 3构建的API文档示例")
                        .termsOfService("https://example.com/terms")
                        .contact(new Contact()
                                .name("开发团队")
                                .email("dev@example.com")
                                .url("https://example.com"))
                        .license(new License()
                                .name("Apache 2.0")
                                .url("https://www.apache.org/licenses/LICENSE-2.0.html")));
    }
}

三、实战示例

1. 创建实体类

package com.example.demo.model;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
@Schema(description = "用户实体类")
public class User {
    
    @Schema(description = "用户ID", example = "1")
    private Long id;
    
    @Schema(description = "用户名", example = "张三")
    private String username;
    
    @Schema(description = "用户年龄", example = "25")
    private Integer age;
    
    @Schema(description = "用户邮箱", example = "zhangsan@example.com")
    private String email;
}

2. 创建控制器

package com.example.demo.controller;

import com.example.demo.model.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.ConcurrentHashMap;

@RestController
@RequestMapping("/api/users")
@Tag(name = "用户管理", description = "用户CRUD操作的API接口")
public class UserController {

    // 模拟数据库
    private static final ConcurrentHashMap<Long, User> users = new ConcurrentHashMap<>();
    
    static {
        users.put(1L, new User(1L, "张三", 25, "zhangsan@example.com"));
        users.put(2L, new User(2L, "李四", 30, "lisi@example.com"));
    }

    @GetMapping
    @Operation(summary = "获取所有用户", description = "返回系统中所有的用户列表")
    @ApiResponse(responseCode = "200", description = "查询成功",
            content = @Content(schema = @Schema(implementation = User.class)))
    public List<User> getAllUsers() {
        return new ArrayList<>(users.values());
    }

    @GetMapping("/{id}")
    @Operation(summary = "根据ID获取用户", description = "根据用户ID查询用户信息")
    @ApiResponse(responseCode = "200", description = "查询成功")
    @ApiResponse(responseCode = "404", description = "用户不存在")
    public ResponseEntity<User> getUserById(
            @Parameter(name = "id", description = "用户ID", in = ParameterIn.PATH, required = true)
            @PathVariable Long id) {
        User user = users.get(id);
        if (user == null) {
            return ResponseEntity.notFound().build();
        }
        return ResponseEntity.ok(user);
    }

    @PostMapping
    @Operation(summary = "创建新用户", description = "添加新用户到系统中")
    @ApiResponse(responseCode = "201", description = "用户创建成功")
    public ResponseEntity<User> createUser(
            @Parameter(description = "用户信息", required = true)
            @RequestBody User user) {
        Long newId = users.size() + 1L;
        user.setId(newId);
        users.put(newId, user);
        return ResponseEntity.status(201).body(user);
    }

    @PutMapping("/{id}")
    @Operation(summary = "更新用户信息", description = "根据ID更新用户信息")
    public ResponseEntity<User> updateUser(
            @Parameter(name = "id", description = "用户ID", in = ParameterIn.PATH, required = true)
            @PathVariable Long id,
            @Parameter(description = "更新后的用户信息", required = true)
            @RequestBody User user) {
        if (!users.containsKey(id)) {
            return ResponseEntity.notFound().build();
        }
        user.setId(id);
        users.put(id, user);
        return ResponseEntity.ok(user);
    }

    @DeleteMapping("/{id}")
    @Operation(summary = "删除用户", description = "根据ID删除用户")
    public ResponseEntity<Void> deleteUser(
            @Parameter(name = "id", description = "用户ID", in = ParameterIn.PATH, required = true)
            @PathVariable Long id) {
        if (!users.containsKey(id)) {
            return ResponseEntity.notFound().build();
        }
        users.remove(id);
        return ResponseEntity.noContent().build();
    }
}

四、常用Swagger注解说明

注解	说明
@Tag	用于描述控制器类的作用
@Operation	用于描述接口方法的作用
@Parameter	用于描述方法参数
@Schema	用于描述实体类或属性
@ApiResponse	用于描述接口的响应信息
@RequestBody	用于描述请求体参数

五、访问Swagger UI

启动Spring Boot应用后，通过以下地址访问Swagger UI界面：

http://localhost:8080/swagger-ui/index.html

在这个界面中，你可以：

1. 查看所有API接口列表
2. 查看每个接口的详细信息（参数、响应等）
3. 在线测试API接口
4. 导出API文档（支持JSON和YAML格式）

六、生产环境配置

在生产环境中，我们通常需要关闭Swagger文档，可以通过配置文件实现：

# application-prod.yml
springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

然后在启动时指定生产环境：

java -jar your-app.jar --spring.profiles.active=prod

总结

通过以上步骤，我们完成了Spring Boot 3与Swagger 3的集成，实现了API文档的自动生成和在线测试功能。Swagger不仅能提高团队协作效率，还能作为API的活文档，随着代码的更新而自动更新。

在实际项目中，可以根据需要进一步定制Swagger配置，如添加全局参数、配置API分组、设置安全认证等，以满足不同场景的需求。

如果文章对你有一点点帮助，欢迎【点赞、留言、+ 关注】，
您的关注是我持续创作的重要动力！有问题欢迎随时交流！多一个朋友多一条路！