SpringBoot整合Swagger详解

在Spring Boot项目中整合Swagger（现在通常指的是SpringDoc，因为它基于OpenAPI 3.0标准）。

步骤 1: 添加依赖

在你的pom.xml中添加以下依赖：

<dependencies>
    <!-- SpringDoc OpenAPI UI -->
    <dependency>
        <groupId>org.springdoc</groupId>

        <artifactId>springdoc-openapi-ui</artifactId>

        <version>1.6.11</version> <!-- 使用最新版本 -->
    </dependency>

    <!-- SpringDoc OpenAPI Data REST (如果使用Spring Data REST) -->
    <dependency>
        <groupId>org.springdoc</groupId>

        <artifactId>springdoc-openapi-data-rest</artifactId>

        <version>1.6.11</version> <!-- 使用最新版本 -->
    </dependency>

</dependencies>

步骤 2: 配置Swagger

创建一个配置类来设置Swagger：

import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("public-api")
                .pathsToMatch("/api/public/**") // 设置API路径前缀
                .build();
    }
}

如果你想在application.yml或application.properties中配置Swagger，可以这样做：

# application.yml
springdoc:
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger-ui.html

步骤 3: 注解你的API

使用@Api和@ApiOperation等注解来描述你的API：

import io.swagger.v3.oas.annotations.Api;
import io.swagger.v3.oas.annotations.Operation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/public")
@Api(tags = "Public API", description = "Public APIs")
public class PublicController {

    @GetMapping("/hello")
    @Operation(summary = "Hello World", description = "Returns a simple greeting")
    public String helloWorld() {
        return "Hello, World!";
    }
}

步骤 4: 测试Swagger UI

启动你的Spring Boot应用，然后在浏览器中访问http://localhost:8080/swagger-ui.html，你将看到一个可交互的API文档界面，可以用来测试你的API。

高级配置

你可以进一步配置Swagger，比如添加安全定义、全局参数、模型描述等等。例如，添加OAuth2安全定义：

import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springdoc.core.converters.models.OpenApiSecurityScheme;

@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("public-api")
                .pathsToMatch("/api/public/**")
                .securitySchemes(Arrays.asList(securityScheme()))
                .build();
    }

    private OpenApiSecurityScheme securityScheme() {
        return new OpenApiSecurityScheme()
                .type(OpenApiSecurityScheme.Type.OAUTH2)
                .name("Authorization")
                .in(OpenApiSecurityScheme.IN_HEADER)
                .flows(new OAuthFlows()
                        .authorizationCode(new OAuthFlow()
                                .tokenUrl("http://localhost:8080/oauth/token")
                                .authorizationUrl("http://localhost:8080/oauth/authorize")
                                .scopes(new Scopes().addString("read", "read all resources"))));
    }
}

你可能需要根据你的具体需求进行更详细的配置。