摘要： Swagger+GetMapping：让你的API文档自动“活”起来在后端开发中，API文档是连接前后端、测试与开发的关键桥梁。但手动写文档不仅耗时，还容易出现“代码改了文档没更”的尴尬——直到Swagger出现，这个问题才被完美解决...

Swagger + GetMapping：让你的API文档自动“活”起来

在后端开发中，API文档是连接前后端、测试与开发的关键桥梁。但手动写文档不仅耗时，还容易出现“代码改了文档没更”的尴尬——直到Swagger出现，这个问题才被完美解决。而当Swagger遇上Spring Boot的@GetMapping注解，更是让API文档从“静态死文档”变成“动态活手册”。今天就来聊聊这对CP如何让你的接口开发效率翻倍。

一、先搞懂：Swagger和GetMapping是什么？

• @GetMapping：Spring Boot中处理HTTP GET请求的核心注解。比如@GetMapping("/users/{id}")，就表示这个方法会响应GET /users/123这样的请求，用来查询ID为123的用户。它帮你快速映射URL和方法，省去了写@RequestMapping(method = RequestMethod.GET)的麻烦。
• Swagger：一款自动生成API文档的工具。它能扫描你的代码中的注解，自动生成可视化的文档页面，还支持在线测试接口——不用再打开Postman输URL、填参数，直接在文档页就能点“Try it out”测试。

二、如何让Swagger“识别”你的GetMapping接口？

整合步骤超简单，3步搞定：

1. 引入依赖（Spring Boot项目）

在pom.xml中添加Swagger的依赖（以Springfox为例）：

<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>

2. 配置Swagger

写一个配置类，开启Swagger并设置基本信息：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yourpackage.controller")) // 扫描你的Controller包
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("用户管理API文档")
                .description("包含用户查询、新增等接口")
                .version("1.0")
                .build();
    }
}

3. 给GetMapping接口加“注释”

在你的Controller方法上，用Swagger注解补充说明：

@RestController
@RequestMapping("/users")
@Api(tags = "用户管理接口") // 给整个Controller加标签
public class UserController {

    @GetMapping("/{id}")
    @ApiOperation("根据ID查询用户") // 接口描述
    @ApiParam(name = "id", value = "用户ID", required = true) // 参数说明
    public UserDTO getUserById(@PathVariable Long id) {
        // 业务逻辑...
        return new UserDTO(id, "张三", 25);
    }
}

三、整合后的“真香”体验

• 自动更新文档：代码改了，文档跟着变——再也不用手动同步文档和代码。
• 可视化界面：启动项目后访问http://localhost:8080/swagger-ui.html，就能看到所有接口的列表，每个接口的参数、返回值、状态码都清晰展示。
• 在线测试：点击接口旁边的“Try it out”，输入参数就能直接发送请求，看返回结果，省去Postman的繁琐操作。
• 协作更高效：前后端开发不用再反复沟通接口细节——直接甩给前端Swagger地址，他们自己看文档、测接口。

四、小技巧：让文档更专业

• 用@ApiImplicitParams描述多个参数：比如分页查询时，说明page和size的含义。
• 用@ApiResponse标注返回状态码：比如@ApiResponse(code = 200, message = "查询成功")、@ApiResponse(code = 404, message = "用户不存在")。
• 用@ApiModel和@ApiModelProperty描述返回对象：比如给UserDTO加注解，说明每个字段的含义。

总结

Swagger + GetMapping，本质上是用“代码注解”代替“手动文档”，让API文档从“负担”变成“助力”。无论是个人开发还是团队协作，这对组合都能帮你节省时间、减少沟通成本。现在就试试吧——你的接口文档，该“活”起来了！

（字数：约750字）

如果需要更深入的细节（比如Swagger3的使用、自定义文档样式），欢迎留言告诉我哦~
关注我，每天分享一个实用的开发小技巧！ ✨
（注：文中代码基于Spring Boot 2.x和Swagger2，若用Spring Boot 3.x，建议升级到SpringDoc OpenAPI~）