JAVA开发在 Spring Boot 中集成 Swagger

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

JAVA开发 在 Spring Boot 中集成 Swagger

在 Spring Boot 中集成 Swagger

1. 添加 Maven 依赖

2. 启用 Swagger

3. 访问 Swagger UI

在 Spring Boot 3.x 中集成 Swagger

1. 添加 Maven 依赖

2. 启用 Swagger

3. 访问 Swagger UI

示例代码

pom.xml

DemoApplication.java

UserController.java

User.java

总结

JAVA开发在 Spring Boot 中集成 Swagger

`pom.xml`

`DemoApplication.java`

`UserController.java`

`User.java`