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 文件中添加以下依赖：

<dependencies>
    

    
    <dependency>
        <groupId>io.springfoxgroupId>
        <artifactId>springfox-swagger2artifactId>
        <version>3.0.0version>
    dependency>

    
    <dependency>
        <groupId>io.springfoxgroupId>
        <artifactId>springfox-swagger-uiartifactId>
        <version>3.0.0version>
    dependency>

    
    <dependency>
        <groupId>io.swagger.core.v3groupId>
        <artifactId>swagger-annotationsartifactId>
        <version>2.2.8version>
    dependency>
    <dependency>
        <groupId>io.swagger.core.v3groupId>
        <artifactId>swagger-modelsartifactId>
        <version>2.2.8version>
    dependency>
dependencies>

2. 启用 Swagger

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

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 文件中添加以下依赖：

<dependencies>
    

    
    <dependency>
        <groupId>org.springdocgroupId>
        <artifactId>springdoc-openapi-starter-webmvc-uiartifactId>
        <version>2.0.4version>
    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

<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.0modelVersion>
    <parent>
        <groupId>org.springframework.bootgroupId>
        <artifactId>spring-boot-starter-parentartifactId>
        <version>3.0.6version>
        <relativePath/> 
    parent>
    <groupId>com.examplegroupId>
    <artifactId>demoartifactId>
    <version>0.0.1-SNAPSHOTversion>
    <name>demoname>
    <description>Demo project for Spring Bootdescription>
    <properties>
        <java.version>17java.version>
    properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-webartifactId>
        dependency>
        
        <dependency>
            <groupId>org.springdocgroupId>
            <artifactId>springdoc-openapi-starter-webmvc-uiartifactId>
            <version>2.0.4version>
        dependency>
        <dependency>
            <groupId>org.projectlombokgroupId>
            <artifactId>lombokartifactId>
            <optional>trueoptional>
        dependency>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-testartifactId>
            <scope>testscope>
        dependency>
    dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.bootgroupId>
                <artifactId>spring-boot-maven-pluginartifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombokgroupId>
                            <artifactId>lombokartifactId>
                        exclude>
                    excludes>
                configuration>
            plugin>
        plugins>
    build>
project>

DemoApplication.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

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", "[email protected]");
        return ResponseEntity.ok(user);
    }
}

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