SpringDoc OpenAPI

Laravel 用 Scribe / API Resource 手写接口文档；Spring Boot 用 SpringDoc OpenAPI：加一个依赖，启动后自动生成一份可交互的 API 文档（Swagger UI），还能从注解/代码自动推导接口描述。

三步启用

1. 依赖

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

2. 启动应用

启动后自动生成两个东西：

• Swagger UI：http://localhost:8080/swagger-ui.html —— 可视化、可点击调用的文档页
• OpenAPI JSON：http://localhost:8080/v3/api-docs —— 机器可读的规范（前端可用来生成类型）

3. 完了，什么都不用配

SpringDoc 自动扫描所有 @RestController，从方法签名、DTO 字段推导出接口定义。代码即文档。

对照 Laravel

Laravel	SpringDoc
Scribe / Scramble（第三方）	官方生态，starter 一键
php artisan scribe:generate	启动即生成，无需命令
手写 annotation 描述	代码 + @Operation 注解
/docs 页面	/swagger-ui.html
openapi.yaml 导出	/v3/api-docs

给接口加描述：@Operation

自动生成的描述不够详细，用注解补充：

@RestController
@RequestMapping("/api/posts")
@Tag(name = "帖子", description = "帖子相关接口")
public class PostController {

    @Operation(summary = "获取帖子列表", description = "分页返回帖子，按创建时间倒序")
    @GetMapping
    public Page<Post> index(Pageable pageable) { ... }

    @Operation(summary = "获取单个帖子")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "成功"),
            @ApiResponse(responseCode = "404", description = "帖子不存在")
    })
    @GetMapping("/{id}")
    public Post show(@PathVariable Long id) { ... }
}

参数描述：@Parameter

@GetMapping("/posts")
public List<Post> search(
        @Parameter(description = "搜索关键词", example = "Spring")
        @RequestParam(required = false) String keyword,
        @Parameter(description = "页码，从 1 开始", example = "1")
        @RequestParam(defaultValue = "1") int page) { ... }

DTO 字段描述：@Schema

@Data
@Schema(description = "创建帖子请求")
public class CreatePostRequest {

    @Schema(description = "标题", example = "Spring Boot 入门")
    @NotBlank
    @Size(max = 100)
    private String title;

    @Schema(description = "正文")
    private String content;
}

鉴权配置：Swagger UI 里带 token 调接口

配置全局 Bearer 认证，让 UI 里可以输入 token 再调接口：

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Blog API")
                        .version("1.0")
                        .description("博客系统接口文档"))
                .components(new Components()
                        .addSecuritySchemes("bearer-jwt", new SecurityScheme()
                                .type(SecurityScheme.Type.HTTP)
                                .scheme("bearer")
                                .bearerFormat("JWT")))
                .addSecurityItem(new SecurityRequirement().addList("bearer-jwt"));
    }
}

生产环境开关

文档只该在开发环境开：

springdoc:
  swagger-ui:
    enabled: true
  api-docs:
    enabled: true

# application-prod.yml 关掉
springdoc:
  swagger-ui:
    enabled: false
  api-docs:
    enabled: false

常用配置

springdoc:
  swagger-ui:
    path: /swagger-ui.html        # UI 路径
  api-docs:
    path: /v3/api-docs            # JSON 路径
  packages-to-scan: com.example.blog.post   # 只扫描某些包

实践建议

1. 接口文档靠 SpringDoc 自动生成，省掉手写文档的维护成本
2. DTO 用 @Schema 把字段含义写清楚，前端看文档即知结构
3. 关键接口（对外 API、支付回调）加 @Operation + @ApiResponses
4. 生产环境关闭文档，或加访问权限

为什么比 Laravel 顺

Laravel 的接口文档要么手写、要么靠 Scribe 的注解推断；SpringDoc 从强类型方法签名 + 反射直接推导，DTP 类的字段自动成为 schema，几乎零成本。这就是 Java 静态类型的红利。