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 文档。

相关推荐
泉城老铁4 分钟前
Spring Boot中实现多线程分片下载
java·spring boot·后端
Issie75 分钟前
ThreadLocal 内存泄漏详解
java
泉城老铁6 分钟前
Spring Boot中实现多文件打包下载
spring boot·后端·架构
泉城老铁6 分钟前
Spring Boot中实现大文件分片下载和断点续传功能
java·spring boot·后端
2501_920047037 分钟前
bash自带的切片操作
开发语言·python·bash
友莘居士8 分钟前
长流程、复杂业务流程分布式事务管理实战
spring boot·rocketmq·saga·复杂流程分布式事务·长流程
master-dragon10 分钟前
java log相关:Log4J、Log4J2、LogBack,SLF4J
java·log4j·logback
奔跑吧邓邓子13 分钟前
【Java实战㉖】深入Java单元测试:JUnit 5实战指南
java·junit·单元测试·实战·junit5
百思可瑞教育14 分钟前
Spring Boot 参数校验全攻略:从基础到进阶
运维·服务器·spring boot·后端·百思可瑞教育·北京百思教育
会当临29 分钟前
【c++】四种类型转换形式
开发语言·c++