Swagger是一个用于设计、构建、记录和使用REST API的开源工具。在Spring Boot项目中集成Swagger可以帮助开发者更方便地查看和测试API。以下是在Spring Boot项目中集成Swagger的详细步骤

 1.添加Swagger依赖

在Spring Boot项目的pom.xml文件中添加Swagger的依赖 这里使用的是3.0.0版本

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version> <!-- 请使用最新版本 -->
</dependency>

2.配置Swagger

在Spring Boot项目的配置文件（通常是application.yml或application.properties）中添加Swagger的配置：

springfox:
  documentation:
    swagger-ui:
      enabled: true
  swagger-ui:
    operations-sorter: alpha
    tags-sorter: alpha

3.创建Swagger配置类

创建一个配置类，用于配置Swagger的Docket bean，这个bean会定义API的基本信息，如API的标题、描述、版本等。例如：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.***.***")) // 替换成你的Controller所在的包名
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Your API Title")
                .description("Your API Description")
                .version("1.0.0")
                .build();
    }
}

4.启动项目并访问Swagger UI

启动你的Spring Boot应用程序，然后访问Swagger UI。默认情况下，Swagger UI的地址是http://localhost:端口号/swagger-ui/，你可以在配置文件中修改。

具体的注解解释：

@Api

  • 用于描述整个Controller的信息。
  • 属性：
  • tags：为API声明一组标签，可以在Swagger UI中用于过滤和组织API。
  • value：API的简要描述。
@Api(tags = "UserController", value = "Operations related to User")

@ApiOperation

  • 描述一个操作（方法）的信息。
  • 属性：
  • value：操作的简要描述。
  • notes：操作的详细描述。
  • response：操作的响应类。
@ApiOperation(value = "Get user by ID", notes = "Provide an ID to look up specific user", response = User.class)

@ApiParam

  • 为操作的参数添加额外的信息。
  • 属性：
  • name：参数的名称。
  • value：参数的简要描述。
  • required：指定参数是否是必需的。
  • defaultValue：参数的默认值。
@ApiParam(name = "id", value = "User ID", required = true, defaultValue = "1")

@ApiImplicitParams

  • 包含多个@ApiImplicitParam注解的容器，用于表示一组操作参数的详细信息。
@ApiImplicitParams({
    @ApiImplicitParam(name = "id", value = "User ID", required = true, defaultValue = "1", paramType = "path"),
    @ApiImplicitParam(name = "name", value = "User Name", required = true, defaultValue = "John", paramType = "query")
})

@ApiResponses

  • 包含多个@ApiResponse注解的容器，表示一组操作的不同响应。
@ApiResponses({
    @ApiResponse(code = 200, message = "OK", response = User.class),
    @ApiResponse(code = 404, message = "User not found")
})

@ApiResponse

  • 描述一个操作的响应信息。
  • 属性：
  • code：HTTP响应码。
  • message：响应消息。
  • response：响应的实体类
@ApiResponse(code = 200, message = "OK", response = User.class)

这些注解可以根据你的具体需求进行组合使用。通过使用Swagger注解，你可以更好地组织和展示API的信息，使得API文档更加清晰和易于理解。