Swagger基本知识及Spring Boot集成指南

原创于 2025-06-13 09:45:15 发布 · 1.5k 阅读

18 ·

CC 4.0 BY-SA版权

文章标签：

#spring boot #后端 #java

Spring 生态工具箱专栏收录该内容

26 篇文章

订阅专栏

一、Swagger简介

1.1 什么是Swagger

Swagger是一套围绕OpenAPI规范构建的开源工具集，用于设计、构建、文档化和消费RESTful Web服务。它提供了一种标准化、语言无关的接口来描述REST API，使人类和计算机都能在不访问源代码、文档或网络流量的情况下发现和理解服务功能。

Swagger的核心组件包括：

Swagger UI：可视化API文档，支持交互式测试
Swagger Editor：基于浏览器的API设计编辑器
Swagger Codegen：根据API规范生成客户端SDK代码
Swagger Core：Java库，用于生成、消费OpenAPI定义

1.2 为什么使用Swagger

自动生成API文档：减少手动编写文档的工作量，保持文档与代码同步
交互式测试：直接在浏览器中测试API，无需额外工具
前后端协作：提供清晰的API契约，促进前后端分离开发
标准化：遵循OpenAPI规范，行业通用标准
减少沟通成本：开发者和使用者对API有统一的理解

二、OpenAPI规范基础

OpenAPI规范(原Swagger规范)是定义RESTful API的标准格式，使用YAML或JSON描述API的以下方面：

可用端点(/users)和操作(GET /users, POST /users)
每个操作的参数输入和输出
认证方法
联系信息、许可证、使用条款等元信息

一个简单的OpenAPI定义示例：

openapi: 3.0.0
info:
  title: Sample API
  description: API description
  version: 1.0.0
servers:
  - url: http://api.example.com/v1
paths:
  /users:
    get:
      summary: Returns a list of users
      responses:
        '200':
          description: A JSON array of user names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

三、Spring Boot集成Swagger

3.1 添加依赖

对于Spring Boot 2.x项目，使用Springfox Swagger实现：

<!-- Swagger 2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- Swagger UI -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

对于Spring Boot 3.x项目，由于Springfox不再维护，推荐使用springdoc-openapi：

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

3.2 基本配置

Springfox配置类示例

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot API文档")
                .description("Spring Boot项目API接口文档")
                .version("1.0")
                .contact(new Contact("作者", "https://example.com", "contact@example.com"))
                .build();
    }
}

springdoc-openapi配置(Spring Boot 3)

application.properties配置：

springdoc.api-docs.path=/api-docs
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.version=1.0.0
springdoc.title=Spring Boot API文档
springdoc.description=Spring Boot项目API接口文档

或通过Java配置：

@Configuration
public class OpenApiConfig {
    
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Spring Boot API文档")
                        .version("1.0")
                        .description("Spring Boot项目API接口文档")
                        .contact(new Contact().name("作者").url("https://example.com").email("contact@example.com")))
                .externalDocs(new ExternalDocumentation()
                        .description("更多信息")
                        .url("https://example.com/docs"));
    }
}

3.3 常用注解

控制器层注解

@Api：标记在Controller类上，描述整个控制器
@ApiOperation：描述单个操作方法
@ApiParam：描述方法参数
@ApiResponse：描述操作响应

@RestController
@RequestMapping("/api/users")
@Api(tags = "用户管理")
public class UserController {

    @GetMapping("/{id}")
    @ApiOperation(value = "获取用户详情", notes = "根据用户ID获取用户详细信息")
    @ApiResponses({
        @ApiResponse(code = 200, message = "成功"),
        @ApiResponse(code = 404, message = "用户不存在")
    })
    public ResponseEntity<User> getUser(
            @PathVariable @ApiParam(value = "用户ID", example = "1") Long id) {
        // 实现代码
    }
}

模型层注解

@ApiModel：描述模型类
@ApiModelProperty：描述模型属性

@ApiModel(description = "用户实体")
public class User {
    
    @ApiModelProperty(value = "用户ID", example = "1")
    private Long id;
    
    @ApiModelProperty(value = "用户名", required = true, example = "john_doe")
    private String username;
    
    @ApiModelProperty(value = "电子邮件", example = "john@example.com")
    private String email;
    
    // getters and setters
}

3.4 分组配置

对于大型项目，可能需要将API分组展示：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    @Bean
    public Docket userApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("用户管理")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.user.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    
    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("产品管理")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.product.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

四、高级配置与最佳实践

4.1 安全配置

集成JWT认证示例：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .securitySchemes(Arrays.asList(apiKey()))
                .securityContexts(Arrays.asList(securityContext()));
    }
    
    private ApiKey apiKey() {
        return new ApiKey("JWT", "Authorization", "header");
    }
    
    private SecurityContext securityContext() {
        return SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.any())
                .build();
    }
    
    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        return Arrays.asList(new SecurityReference("JWT", new AuthorizationScope[]{authorizationScope}));
    }
}

4.2 生产环境考虑

禁用Swagger UI：生产环境可以通过配置禁用

springfox.documentation.enabled=false
# 或对于springdoc
springdoc.swagger-ui.enabled=false

访问限制：通过Spring Security限制访问

@Override
protected void configure(HttpSecurity http) throws Exception {
    http
        .authorizeRequests()
            .antMatchers("/swagger-ui/**", "/v3/api-docs/**").hasRole("ADMIN")
            // 其他配置
}

版本控制：API文档与API版本保持一致

4.3 文档优化建议

提供详细描述：为每个API和模型属性添加有意义的描述
使用示例值：@ApiModelProperty(example = "value")提供示例数据
标记必填字段：@ApiModelProperty(required = true)
统一响应格式：使用@ApiResponse描述所有可能的响应
分组管理：大型项目按功能模块分组展示API

五、常见问题与解决方案

Swagger UI无法访问404
- 检查依赖是否正确添加
- 确认路径是否正确(默认/swagger-ui.html或/swagger-ui/index.html)
- 检查是否有拦截器拦截了请求
模型属性未显示
- 确保模型类有getter方法
- 检查是否使用了@ApiModelProperty注解

日期时间格式问题

使用@JsonFormat指定格式

@ApiModelProperty(value = "创建时间", example = "2023-01-01 12:00:00")
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
private LocalDateTime createTime;

枚举类型显示问题

在枚举值上添加@ApiModelProperty：

public enum Status {
    @ApiModelProperty("待处理")
    PENDING,
    
    @ApiModelProperty("已完成")
    COMPLETED
}

六、总结

Swagger作为API文档工具，为Spring Boot项目提供了强大的支持：

开发阶段：减少文档编写工作量，支持快速迭代
测试阶段：提供交互式测试界面，方便验证API
协作阶段：作为前后端沟通的契约，减少理解偏差
维护阶段：文档与代码同步更新，降低维护成本

随着OpenAPI规范的普及，Swagger已成为现代API开发的标准工具之一。无论是小型项目还是大型企业级应用，合理使用Swagger都能显著提高开发效率和API质量。

提示：本文基于Spring Boot 2.x和Swagger 2编写。对于Spring Boot 3.x用户，建议使用springdoc-openapi实现，其配置更为简洁，且支持OpenAPI 3.0规范。