【Java开发300个实用技巧】188.接口文档Swagger

精通代码大仙

于 2025-05-23 08:19:37 发布

阅读量644

点赞数 8

分类专栏： Java开发300个实用技巧文章标签： java 开发语言程序员创富

本文链接：https://blog.csdn.net/jrckkyy/article/details/147852877

版权

Java开发300个实用技巧专栏收录该内容

182 篇文章

订阅专栏

在这里插入图片描述

接口文档写不好，前后端打架少不了！Swagger让你从“文档奴隶”变“API掌控者”

安装配置踩坑记
注解使用三大金刚
分组管理黑科技
调试技巧大揭秘
安全与扩展实战
最佳实践指南

嗨，你好呀，我是你的老朋友精通代码大仙。接下来我们一起学习Java开发中的300个实用技巧，震撼你的学习轨迹！

“接口文档就像程序员的遗嘱——活着的时候没人看，出事了全来找！” 是不是经常遇到前端说接口参数不对，测试抱怨文档过期，自己改个参数还要群发邮件？今天我们就用Swagger这把瑞士军刀，彻底终结这些糟心事！

1. 安装配置踩坑记

点题：90%新手倒在这第一步
痛点案例：

// 错误示范：直接引入starter导致版本冲突
implementation 'io.springfox:springfox-boot-starter:3.0.0'

启动直接报错：Failed to start bean 'documentationPluginsBootstrapper'

正确姿势：

// 精准控制依赖版本
implementation 'io.springfox:springfox-swagger2:3.0.0'
implementation 'io.springfox:springfox-swagger-ui:3.0.0'

配置要点：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
          .select()
          .apis(RequestHandlerSelectors.basePackage("com.yourpackage"))
          .paths(PathSelectors.any())
          .build();
    }
}

避坑指南：访问http://localhost:8080/swagger-ui/时看到404？试试加上/swagger-ui/index.html

2. 注解使用三大金刚

点题：掌握这三个注解就能玩转80%场景
场景一（接口说明）：

@ApiOperation(value = "获取用户详情", notes = "需要管理员权限", response = User.class)
@GetMapping("/users/{id}")

场景二（参数说明）：

@ApiParam(name = "id", value = "用户ID", required = true, example = "123") 
@PathVariable Long id

场景三（实体类说明）：

@ApiModel(description = "用户实体")
public class User {
    @ApiModelProperty(value = "用户年龄", example = "18")
    private Integer age;
}

3. 分组管理黑科技

痛点场景：微服务项目里200+接口挤在一个页面
解决方案：

// 支付模块接口组
@Bean
public Docket payApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .groupName("支付模块")
        .select()
        .paths(PathSelectors.ant("/api/pay/**"))
        .build();
}

// 用户模块接口组
@Bean 
public Docket userApi() {
    return new Docket(...)
        .groupName("用户模块")
        .paths(PathSelectors.ant("/api/user/**"))
}

效果展示：文档右上角出现分组下拉框，不同模块井水不犯河水

4. 调试技巧大揭秘

隐藏技巧一（在线调试）：
在Swagger页面直接点击"Try it out"，修改参数后执行，比Postman还方便

隐藏技巧二（文件上传）：

@ApiOperation("上传头像")
@PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public void upload(@RequestPart("file") MultipartFile file) {
    // 参数名必须与@RequestPart一致
}

Swagger页面自动出现文件选择按钮

5. 安全与扩展实战

安全防护（生产环境禁用）：

@Profile("!prod")
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    // 配置内容
}

自定义UI：

/* 覆盖默认样式 */
.swagger-ui .topbar {
    background-color: #3273dc !important;
}

修改resources/static/swagger-ui/css/custom.css即可换肤

6. 最佳实践指南

规范建议：

实体类字段必须添加@ApiModelProperty
接口版本号通过分组管理（v1、v2）
生产环境通过nginx添加basic认证

文档导出：
使用swagger2markup+maven插件生成PDF/HTML文档：

<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>1.3.3</version>
</plugin>