如何使用Swagger自动生成接口文档？

wen PHP项目 2026-06-06 42

如何使用Swagger自动生成接口文档（完整指南）

📖 目录导读

什么是Swagger？它为什么能自动生成接口文档？
快速开始：Spring Boot集成Swagger的5步配置
核心注解详解：用代码注释“画”出专业文档
高级技巧：如何定制文档显示、分组与鉴权
常见问题问答（FAQ）
总结与最佳实践

什么是Swagger？它为什么能自动生成接口文档？

Q：手动写接口文档又累又容易过期，Swagger怎么解决这个问题？

如何使用Swagger自动生成接口文档？

A：Swagger是一个基于OpenAPI规范的接口文档自动生成工具，它的核心原理是：在代码中通过注解描述接口的请求参数、响应结构、错误码等信息，Swagger在运行时扫描这些注解，自动生成一份可交互的HTML文档，这意味着你只要维护代码，文档就会同步更新，彻底告别“代码已改，文档没变”的尴尬。

和传统工具（如Postman、Javadoc）相比,Swagger的三大优势是：

零手工编写：注解即文档
交互式调试：文档页直接“Try it out”调用接口
标准化输出：支持导出JSON/YAML，对接其他工具（如Postman、Kubernetes）

快速开始：Spring Boot集成Swagger的5步配置

Q：新手如何在Spring Boot项目中快速集成Swagger？

A：以最流行的Springfox实现为例，只需5步（以Spring Boot 2.x + Maven为例）：

步骤1：添加Maven依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

注：Spring Boot 3.x建议使用springdoc-openapi（见文末FAQ）

步骤2：创建Swagger配置类

@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XX项目接口文档")
                .description("包含用户、订单等模块")
                .version("1.0")
                .build();
    }
}

步骤3：在Controller中添加Swagger注解

@RestController
@RequestMapping("/user")
@Api(tags = "用户管理")
public class UserController {
    @GetMapping("/{id}")
    @ApiOperation("根据ID获取用户信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true)
    public User getUser(@PathVariable Long id) {
        // ...
    }
}

步骤4：启动项目，访问文档

启动应用后，浏览器访问：http://localhost:8080/swagger-ui/index.html
你会看到自动生成的接口列表，每个接口都可点击展开查看请求参数、响应模型,并直接调试。

步骤5：补充模型注解（优化响应结构显示）

@ApiModel("用户实体")
public class User {
    @ApiModelProperty("用户ID")
    private Long id;
    @ApiModelProperty("昵称")
    private String name;
}

效果：文档中会清晰显示每个字段的类型、是否必填、示例值,甚至支持枚举值提示。

核心注解详解：用代码注释“画”出专业文档

Q：Swagger的注解那么多，哪些是必须掌握的？

A：掌握以下7组注解，足以覆盖90%的场景,按使用频率排序：

1 类级别注解

注解	位置	作用
`@Api`	Controller类	描述模块名称、说明
`@ApiModel`	实体类	定义数据模型名称
`@ApiModelProperty`	实体字段	描述字段含义、是否必填、示例值

2 方法级别注解

注解	位置	作用
`@ApiOperation`	方法上	描述接口功能、备注、响应消息
`@ApiResponses`	方法上	定义不同返回码的响应说明（适配错误场景）

3 参数级别注解

注解	位置	作用
`@ApiImplicitParam`	方法上	描述单个参数（名称、类型、是否必填）
`@ApiParam`	参数前	与@RequestParam/PathVariable配合，描述入参

示例：完整版注解组合

@ApiOperation("批量查询用户")
@ApiResponses({
    @ApiResponse(code = 200, message = "成功，返回用户列表"),
    @ApiResponse(code = 404, message = "没有匹配用户")
})
@GetMapping("/batch")
public List<User> batchQuery(
    @ApiParam("用户ID集合，逗号分隔") 
    @RequestParam String ids) {
    // ...
}

避坑指南：@ApiIgnore注解可让某个方法不出现在文档中（适合内部接口或健康检查接口）。

高级技巧：如何定制文档显示、分组与鉴权

Q：项目模块很多，文档太乱；或者文档需要登录才能看，怎么办？

A：利用Swagger的配置能力可轻松解决：

1 按模块分组显示

@Bean
public Docket userApi() {
    return new Docket(DocumentationType.OAS_30)
            .groupName("用户模块")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.controller.user"))
            .build();
}
@Bean
public Docket orderApi() {
    return new Docket(DocumentationType.OAS_30)
            .groupName("订单模块")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.controller.order"))
            .build();
}

访问时URL参数加上?group=用户模块,就能只看该模块的接口。

2 添加全局鉴权（JWT Token）

@Bean
public Docket api() {
    return new Docket(DocumentationType.OAS_30)
            .securitySchemes(securitySchemes())
            .securityContexts(securityContexts())
            // ...其他配置
}
private List<SecurityScheme> securitySchemes() {
    return List.of(new ApiKey("JWT", "Authorization", "header"));
}
private List<SecurityContext> securityContexts() {
    return List.of(SecurityContext.builder()
            .securityReferences(List.of(new SecurityReference("JWT", new AuthorizationScope[0])))
            .build());
}

这样文档右上角会出现“Authorize”按钮,输入Token后所有请求会自动带上Header。

3 自定义页面样式

在application.yml中添加：

springfox:
  documentation:
    swagger-ui:
      enabled: true
      config-url: /v3/api-docs/swagger-config
  paths-to-match: /api/**   # 限制只扫描/api开头的路径

4 生产环境关闭Swagger

@Configuration
@ConditionalOnProperty(name = "swagger.enabled", havingValue = "true", matchIfMissing = false)
@EnableOpenApi
public class SwaggerConfig {
    // ...
}

在application-prod.yml中设置swagger.enabled=false即可。

常见问题问答（FAQ）

Q1：Swagger和SpringDoc有什么区别？该选哪个？

A：Swagger（Springfox）是经典方案，但已多年未更新（最新版本3.0.0发布于2020年）。SpringDoc是新一代工具，适配Spring Boot 3.x/2.x，支持OpenAPI 3标准，配置更简洁，如果你是新建项目（尤其是Spring Boot 3.x），建议直接使用SpringDoc（依赖：springdoc-openapi-starter-webmvc-ui）,但注解仍然兼容Swagger标准。

Q2：为什么文档显示 “Unable to infer base url”？

A：通常是配置类中RequestHandlerSelectors.basePackage路径写错，或者Controller类没有使用@RestController注解，检查：包名是否完全匹配,Controller是否暴露了有效API路径。

Q3：生成的文档太慢，怎么办？

A：在application.yml设置：

springfox:
  documentation:
    auto-startup: false   # 延迟初始化
    swagger-ui:
      try-it-out-enabled: false  # 禁用交互式调试可提升加载速度

Q4：如何让参数显示默认值/示例值？

A：在@ApiModelProperty中添加example属性：

@ApiModelProperty(value = "年龄", example = "18")
private Integer age;

总结与最佳实践

Q：团队使用Swagger文档的最佳流程是什么？

A：建议遵循以下原则，避免文档“再次腐烂”：

注解规范化：为每个实体类的字段添加@ApiModelProperty（至少说明含义和示例值），为每个接口添加@ApiOperation和@ApiResponses。
版本同步机制：将API版本号写入文档标题，V2.1用户服务接口文档”,发版时同步更新version。
自动化测试融合：将Swagger导出的openapi.json导入Postman或JMeter,可快速生成接口测试脚本。
文档审查：每个Pull Request要求必须包含Swagger注解的变更,否则由测试人员打回。
不滥用分组：分组别超过3个层级（如：产品-模块-子模块）,否则团队成员难以找到接口。