JAVA开发 在 Spring Boot 中集成 Swagger

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

在 Spring Boot 中集成 Swagger

Spring Boot 结合 Swagger 可以通过 springfox-swagger2springfox-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-swagger2springfox-swagger-ui 依赖。
    • 创建配置类启用 Swagger。
  • Spring Boot 3.x:

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

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

相关推荐
间彧几秒前
Spring Boot项目中如何自定义线程池
java
间彧21 分钟前
Java线程池详解与实战指南
java
用户2986985301429 分钟前
Java 使用 Spire.PDF 将PDF文档转换为Word格式
java·后端
后端小张34 分钟前
基于飞算AI的图书管理系统设计与实现
spring boot
渣哥38 分钟前
ConcurrentHashMap 1.7 vs 1.8:分段锁到 CAS+红黑树的演进与性能差异
java
间彧1 小时前
复用线程:原理详解与实战应用
java
咖啡Beans2 小时前
使用OpenFeign实现微服务间通信
java·spring cloud
我不是混子2 小时前
说说单例模式
java
间彧5 小时前
SimpleDateFormat既然不推荐使用,为什么java 8+中不删除此类
java