giuseppe-trisciuoglio/spring-boot-openapi-documentation

spring-boot-openapi-documentation 是做什么的？

提供在 Spring Boot 3.x 应用程序中使用 SpringDoc OpenAPI 3.0 和 Swagger UI 生成全面 REST API 文档的模式。适用于设置 API 文档、配置 Swagger UI、添加 OpenAPI 注解、实现安全文档或使用示例和模式增强 REST 端点。

入门指南

前提条件

• Spring Boot 3.x 项目
• Maven 或 Gradle 构建系统

添加依赖

对于 Maven，在 pom.xml 中添加：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

对于 Gradle，在 build.gradle 中添加：

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'

配置 OpenAPI

创建一个配置类以自定义 OpenAPI 信息：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("API 文档")
                        .version("1.0")
                        .description("这是使用 SpringDoc OpenAPI 3.0 的 Spring Boot REST API 文档")
                        .contact(new Contact()
                                .name("你的名字")
                                .email("[email protected]")
                                .url("https://example.com"))
                        .license(new License()
                                .name("Apache 2.0")
                                .url("http://springdoc.org")));
    }
}

使用注解

使用 OpenAPI 注解增强控制器：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
@Tag(name = "用户管理", description = "用户管理端点")
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "按 ID 获取用户", description = "根据用户 ID 返回用户详细信息")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "成功获取用户"),
        @ApiResponse(responseCode = "404", description = "未找到用户"),
        @ApiResponse(responseCode = "500", description = "内部服务器错误")
    })
    public User getUserById(@PathVariable Long id) {
        // 实现详情
        return new User();
    }
}

使用 DTO 和示例

为更好的文档定义 DTO：

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "用户 DTO")
public class User {
    
    @Schema(description = "用户 ID", example = "1")
    private Long id;
    
    @Schema(description = "用户名", example = "john_doe")
    private String username;
    
    @Schema(description = "用户邮箱", example = "[email protected]")
    private String email;
    
    // getters 和 setters
}

添加安全文档

配置安全方案（例如 JWT Bearer Token）：

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiSecurityConfig {

    private static final String SECURITY_SCHEME_NAME = "bearerAuth";

    @Bean
    public OpenAPI securedOpenAPI() {
        return new OpenAPI()
                .components(new Components()
                        .addSecuritySchemes(SECURITY_SCHEME_NAME, new SecurityScheme()
                                .name(SECURITY_SCHEME_NAME)
                                .type(SecurityScheme.Type.HTTP)
                                .scheme("bearer")
                                .bearerFormat("JWT")))
                .addSecurityItem(new SecurityRequirement().addList(SECURITY_SCHEME_NAME));
    }
}

访问 Swagger UI

添加依赖并配置后，在以下地址访问 Swagger UI：

http://localhost:8080/swagger-ui/index.html

OpenAPI 规范文档在以下地址：

http://localhost:8080/v3/api-docs

配置属性

在 application.properties 或 application.yml 中：

springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.packages-to-scan=com.example.controller
springdoc.paths-to-match=/api/**

常见问题排查

• 如果 Swagger UI 未加载，请检查是否正确添加了依赖。
• 确保 Spring Boot 版本为 3.x。
• 如果有安全配置，确保 Swagger UI 端点是公开的。
• 验证扫描包配置是否覆盖了你的控制器。