Swagger API文档：Java RESTful服务的自动生成

Swagger 简介

Swagger 是一套用于设计、构建、文档化和消费 RESTful API 的开源工具集。通过 Swagger，可以自动生成 API 文档，并提供交互式测试界面。

集成 Swagger 到 Java RESTful 服务

添加 Maven 依赖

在 pom.xml 文件中添加以下依赖：

XML 复制代码

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

配置 Swagger

创建 Swagger 配置类：

java 复制代码

@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("RESTful API 文档")
                .description("Java RESTful 服务接口")
                .version("1.0")
                .build();
    }
}

启用 Swagger UI

启动应用后，访问 http://localhost:8080/swagger-ui.html 即可查看自动生成的 API 文档并进行测试。

常用 Swagger 注解

接口描述

@Api：标注控制器类，提供接口分组信息。
@ApiOperation：标注方法，描述接口功能。
@ApiParam：标注方法参数，说明参数含义。

数据模型

@ApiModel：标注实体类，说明模型用途。
@ApiModelProperty：标注字段，描述属性信息。

示例代码

控制器示例

java 复制代码

@RestController
@RequestMapping("/api/users")
@Api(tags = "用户管理")
public class UserController {
    @GetMapping("/{id}")
    @ApiOperation("根据 ID 查询用户")
    public User getUser(@PathVariable @ApiParam("用户 ID") Long id) {
        return userService.getUserById(id);
    }
}

实体类示例

java 复制代码

@ApiModel("用户信息")
public class User {
    @ApiModelProperty("用户 ID")
    private Long id;

    @ApiModelProperty("用户名")
    private String name;
}

升级到 OpenAPI 3.0

如需使用 Swagger 3.0（OpenAPI 3.0），可替换依赖为：

XML 复制代码

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.12</version>
</dependency>

访问地址变更为 modelscope.cn/learn/71516
modelscope.cn/learn/71514
modelscope.cn/learn/71512
modelscope.cn/learn/71510
modelscope.cn/learn/71508
modelscope.cn/learn/71506
modelscope.cn/learn/71504
modelscope.cn/learn/71502
modelscope.cn/learn/71500
modelscope.cn/learn/71498
modelscope.cn/learn/71496
modelscope.cn/learn/71493
modelscope.cn/learn/71492
modelscope.cn/learn/71489
modelscope.cn/learn/71488
modelscope.cn/learn/71485
modelscope.cn/learn/71484
modelscope.cn/learn/71482
modelscope.cn/learn/71480
modelscope.cn/learn/71478
modelscope.cn/learn/71476
modelscope.cn/learn/71474
modelscope.cn/learn/71472
modelscope.cn/learn/71470
modelscope.cn/learn/71469
modelscope.cn/learn/71466
modelscope.cn/learn/71465
modelscope.cn/learn/71462
modelscope.cn/learn/71460
modelscope.cn/learn/71458
modelscope.cn/learn/71456
modelscope.cn/learn/71454
modelscope.cn/learn/71452
modelscope.cn/learn/71450
modelscope.cn/learn/71448
modelscope.cn/learn/71445
modelscope.cn/learn/71444
modelscope.cn/learn/71441
modelscope.cn/learn/71440
modelscope.cn/learn/71438
modelscope.cn/learn/71436
modelscope.cn/learn/71434
modelscope.cn/learn/71432
modelscope.cn/learn/71430
modelscope.cn/learn/71427
modelscope.cn/learn/71426
modelscope.cn/learn/71423
modelscope.cn/learn/71422
modelscope.cn/learn/71419
modelscope.cn/learn/71418

总结

Swagger 能够大幅提升 API 开发效率，自动生成文档并支持在线测试。通过合理使用注解，可以增强文档的可读性和实用性。