Swagger：API世界的“导游”与“代言人”-优快云博客

本文链接：https://blog.youkuaiyun.com/m0_70590680/article/details/144455328

文章目录

Swagger：API世界的“导游”与“代言人”

在编写 API 的道路上，Swagger 就像一位风趣的导游，不仅帮你规划路线，还会时不时给你讲个笑话，让你原本枯燥的旅程变得充满乐趣和秩序。今天，让我们用轻松的方式聊聊 Swagger 和它的那些“小伙伴们”。

一、Swagger 是什么？

简单点说，Swagger 是 API 界的“明星”，它不仅会帮你设计 API，还能一键生成文档，让前后端小伙伴们一目了然。
它的典型台词是：“别慌，有我在！”

你写的接口有多复杂，它就能帮你多忙活。生成文档、测试接口、生成客户端代码——全都不在话下！

二、Swagger 的核心技能

自动化文档生成
Swagger 就像一个 API 速写师，随便扫一眼你的代码，就能画出一幅详尽的“说明书”。
交互式调试工具
还记得那些年手写 Postman 测试接口的日子吗？Swagger 的 Swagger UI 工具简直是 Postman 的亲戚，直接在页面上调试接口，轻轻松松点几下就完事了。
标准化规范
在 Swagger 面前，没有“野路子”接口。它会用标准的格式把你的 API 梳理得明明白白。

三、Swagger 的江湖地位

Swagger 是一种“语言”，用开发者都听得懂的方式告诉大家：“这个 API 是干嘛的！”

后端开发：不需要天天回答“这个字段是啥意思”的灵魂拷问。
前端开发：终于不用再猜接口格式了，轻松拷贝 Swagger 提供的请求示例就能跑起来。
测试工程师：可以直接点点 Swagger 页面，轻松生成各种测试用例。

四、Swagger 的常用注解，戏精小分队登场！

Swagger 的魅力不仅在于它的功能，还在于它“戏精附体”的注解，像一群个性鲜明的小伙伴，让你的代码活灵活现。

1. @Api

Swagger 世界的大门钥匙，专门标注在类上，给整个接口组起个“好听的名字”。

剧场版台词：

“来来来，这是用户管理的接口集合，别走错片场！”

示例：

@Api(value = "用户管理接口", tags = {"用户操作"})
@RestController
public class UserController {
}

2. @ApiOperation

每个接口的“小标题”，用来告诉大家这个接口是干嘛的。

剧场版台词：

“这个接口可厉害了，它能帮你获取用户信息，记得点赞收藏！”

示例：

@ApiOperation(value = "获取用户信息", notes = "通过用户 ID 获取详细信息")
@GetMapping("/user/{id}")
public User getUser(@PathVariable Long id) {
    return userService.getUserById(id);
}

3. @ApiParam

专注于接口参数的戏精，帮你描述每个参数是干啥的。

剧场版台词：

“请填写用户 ID，别乱填哦，否则 API 哭给你看！”

示例：

@DeleteMapping("/user/{id}")
@ApiOperation("删除用户")
public void deleteUser(
        @ApiParam(value = "用户 ID", required = true) 
        @PathVariable Long id) {
    userService.deleteUser(id);
}

4. @ApiModel & @ApiModelProperty

Swagger 的“艺术家”，专门给你的实体类画草图。

剧场版台词：

“这个类就是用户模型啦，下面的字段描述可是相当细致哦！”

示例：

@ApiModel(value = "用户信息模型", description = "这是用户的详细信息")
public class User {
    @ApiModelProperty(value = "用户 ID", example = "1")
    private Long id;

    @ApiModelProperty(value = "用户名", example = "jack")
    private String username;
}

5. @ApiResponses

负责解释接口的返回结果，仿佛在接口的演出结束后给观众发放“答题卡”。

剧场版台词：

“成功的话返回用户信息，失败的话记得看状态码哦！”

示例：

@ApiResponses({
    @ApiResponse(code = 200, message = "操作成功", response = User.class),
    @ApiResponse(code = 404, message = "用户未找到")
})

五、一键生成文档的快感

用了 Swagger 之后，最爽的就是不用手写文档了！下面是完整的集成步骤：

第一步：引入依赖

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

第二步：配置 Swagger

@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}