JAVA开发 在 Spring Boot 中集成 Swagger

天之涯上上2024-12-26 10:08

Swagger 是一个广泛使用的 API 文档生成工具，可以帮助你自动生成和维护 RESTful API 的文档。在不同的框架中集成 Swagger 通常需要添加相应的依赖项。以下是几种常见 Java 框架（如 Spring Boot）中集成 Swagger 的依赖配置。

在 Spring Boot 中集成 Swagger

Spring Boot 结合 Swagger 可以通过 springfox-swagger2 和 springfox-swagger-ui 库来实现。以下是如何在 Spring Boot 项目中添加这些依赖的步骤。

1. 添加 Maven 依赖

在你的 pom.xml 文件中添加以下依赖：

xml 复制代码 
<dependencies>
    <!-- 其他依赖 -->

    <!-- Springfox Swagger2 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>3.0.0</version>
    </dependency>

    <!-- Springfox Swagger UI -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>3.0.0</version>
    </dependency>

    <!-- 如果使用的是 Spring Boot 3.x, 需要额外添加 swagger-models -->
    <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>2.2.8</version>
    </dependency>
    <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-models</artifactId>
        <version>2.2.8</version>
    </dependency>
</dependencies>
2. 启用 Swagger

创建一个配置类来启用 Swagger 并配置其基本信息。

java 复制代码 
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yourpackage.controller")) // 替换为你的控制器包路径
                .paths(PathSelectors.any())
                .build();
    }
}
3. 访问 Swagger UI

启动你的 Spring Boot 应用后，可以通过以下 URL 访问 Swagger UI：

复制代码 
http://localhost:8080/swagger-ui/index.html

在 Spring Boot 3.x 中集成 Swagger

由于 Spring Boot 3.x 使用了 Jakarta EE，一些库可能需要更新版本。以下是适用于 Spring Boot 3.x 的依赖配置。

1. 添加 Maven 依赖

在你的 pom.xml 文件中添加以下依赖：

xml 复制代码 
<dependencies>
    <!-- 其他依赖 -->

    <!-- OpenAPI 3.x for Spring Boot 3.x -->
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>2.0.4</version>
    </dependency>
</dependencies>
2. 启用 Swagger

对于 Spring Boot 3.x，通常不需要额外的配置类，因为 springdoc-openapi-starter-webmvc-ui 会自动配置 Swagger。

3. 访问 Swagger UI

启动你的 Spring Boot 应用后，可以通过以下 URL 访问 Swagger UI：

复制代码 
http://localhost:8080/swagger-ui/index.html

示例代码

以下是完整的示例代码，展示了如何在 Spring Boot 3.x 项目中集成 Swagger。

pom.xml
xml 复制代码 
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.0.6</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>demo</name>
    <description>Demo project for Spring Boot</description>
    <properties>
        <java.version>17</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- OpenAPI 3.x for Spring Boot 3.x -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.0.4</version>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>
DemoApplication.java
java 复制代码 
package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}
UserController.java
java 复制代码 
package com.example.demo.controller;

import com.example.demo.model.User;
import io.swagger.v3.oas.annotations.Operation;
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.*;

@RestController
@RequestMapping("/api/users")
@Tag(name = "User Management", description = "Endpoints for managing users")
public class UserController {

    @Operation(summary = "Create a new user", responses = {
            @ApiResponse(responseCode = "201", description = "User created successfully",
                    content = @Content(schema = @Schema(implementation = User.class))),
            @ApiResponse(responseCode = "400", description = "Invalid input"),
            @ApiResponse(responseCode = "500", description = "Internal server error")
    })
    @PostMapping("/")
    public ResponseEntity<User> createUser(@RequestBody User user) {
        // 处理用户创建逻辑
        return ResponseEntity.ok(user);
    }

    @Operation(summary = "Get a user by ID", responses = {
            @ApiResponse(responseCode = "200", description = "User found",
                    content = @Content(schema = @Schema(implementation = User.class))),
            @ApiResponse(responseCode = "404", description = "User not found"),
            @ApiResponse(responseCode = "500", description = "Internal server error")
    })
    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        // 处理获取用户逻辑
        User user = new User(id, "John Doe", "john.doe@example.com");
        return ResponseEntity.ok(user);
    }
}
User.java
java 复制代码 
package com.example.demo.model;

import lombok.Data;

@Data
public class User {
    private Long id;
    private String name;
    private String email;
}

总结

  • Spring Boot 2.x:

    • 添加 springfox-swagger2 和 springfox-swagger-ui 依赖。
    • 创建配置类启用 Swagger。

  • Spring Boot 3.x:

    • 添加 springdoc-openapi-starter-webmvc-ui 依赖。
    • 不需要额外的配置类，springdoc-openapi-starter-webmvc-ui 会自动配置 Swagger。

通过以上步骤，你可以在 Spring Boot 项目中成功集成 Swagger，并生成和查看 API 文档。

相关推荐
Web极客码6 小时前
用 Python 搭建工具调用 Agent 的调试过程
java·服务器·前端
云烟成雨TD6 小时前
Micrometer 系列【33】Spring Boot Micrometer Metrics 自动配置模块解析
spring boot·云原生·micrometer
我命由我123456 小时前
Android 控件 - CardView（快速实现圆角）
android·java·java-ee·kotlin·android studio·android-studio·android runtime
2601_963869956 小时前
【计算机毕业设计】基于Java的潮牌购物网站系统的设计与实现
java·开发语言·课程设计
203号居民6 小时前
LeetCode hot 100 —560. 和为 K 的子数组
java·算法·leetcode
名字还没想好☜6 小时前
Go 的 io.Reader/Writer 组合实战:io.Copy、TeeReader、MultiWriter 优雅处理数据流
开发语言·后端·golang·go·iphone
浪客川6 小时前
使用 IDEA 生成API文档
java·ide·intellij-idea
郝学胜-神的一滴6 小时前
Qt 高级编程 042：进度条从入门到自定义美化
开发语言·c++·qt·软件开发·用户界面
鸿芯微控科技7 小时前
压电纳米定位分辨率怎么测？噪声、带宽、最小可检测位移与Python分析
开发语言·python·噪声分析·压电执行器·纳米定位·位移测量
会编程的土豆7 小时前
从「锁」到「时间」：后端里几个容易混的概念
java·开发语言·数据库·goland
热门推荐
01VSCode+CodeX扩展，无法启动02GitHub 镜像站点03国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）04如何新建文件夹？ 电脑新建文件夹的4种方法052026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？06微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新07历年考研数学一、数学二、数学三真题试卷及答案PDF08Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费09AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路102026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片