什么是swagger，一篇带你入门
一、前言
在前后端分离开发的过程中，前端和后端需要进行api对接进行交互，就需要一个api规范文档，方便前后端的交互，但api文档不能根据代码的变化发生实时动态的改变，这样后端修改了接口，前端不能及时获取最新的接口，导致调用出错，需要手动维护api文档，加大了开发的工作量和困难，而swagger的出现就是为了解决这一系列的问题。
二、swagger的概述
swagger是一套基于OpenAPI规范构建的开源工具，使用RestApi
1、代码变，文档变
2、跨语言，支持多种语言
3、swagger-ui 呈现出来的是一份可交互式的API文档，可以直接在文档页面尝试API的调用
4、可以将文档规范导入相关工具（postman、soapui），这些工具将会为我们自动地创建自动化测试
补充：
RestApi格式是根据请求的方式决定本次请求的一个操作，譬如：get-->读，post-->写（增、删、改），put-->修改，delete-->删除
OpenApi与语言无关，只是一种规范，可以使用yaml和json格式进行编写，这样更利于我们和机器进行阅读
swagger主要包含了以下三个部分：
- swagger editor：基于浏览器的编辑器，我们可以使用它编写我们OpenApi规范(yaml或者json配置）
- Swagger UI：他会将我们编写的OpenApi规范呈现为交互式的API文档，后文我将使用浏览器来查看并且操作我们的RestApi
- Swagger Codegen：它可以通过OpenApi规范定义的任何API生成服务器存根和客户端SDK来简化构建过程
使用swagger就是把相关信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码
三、springfox概述
使用swagger时如果碰见版本更新迭代时，只需要更改swagger的描述文件即可，但是在频繁的更新项目版本时很多开发人员认为即使修改描述文件（yml或json文件）也是一定的工作负担，久而久之就直接修改代码，而不去修改描述文件了，这样基于描述文件生成接口文档也失去了意义。
Marty Pitt编写了一个基于spring的组件swagger-springmvc,Spring-fox就是根据这个组件发展而来的全新项目;
Spring-fox是根据代码生成接口文档，所以正常的进行更新项目版本，修改代码即可，而不需要跟随修改描述文件(yml或json文件）;
spring-fox利用自身AOP特性，把swagger集成进来，底层还是Swagger，但是使用起来却方便很多，所以在实际开发中，都是直接使用spring-fox。
四、swagger的使用
1、新建springboot项目
2、导入相关依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
3、启动类中添加@EnableSwagger2注解
@enableSwagger2：是springfox提供的一个注解，代表swagger2相关技术开启,会扫描当前类所在包，以及子包中所有的类型中的注解，做swagger文档的定值
4、编写一个简单api接口
@RestController public class HelloController { @GetMapping("/get") public String get() { return "get"; } @PostMapping("/post") public String post() { return "post"; } @RequestMapping("/hello") public String hello() { return "hello"; } }
5、启动项目，并在浏览器输入http://localhost:8080/swagger-ui.html进行swagger-ui界面访问
4.1 swagger的基础信息配置-->config类
@Configuration @EnableSwagger2 //开启swagger2,若启动类上添加了该注解，则配置类可以不添加 public class SwaggerConfig { // 创建swagger bean @Bean public Docket docket() { // Docket是swagger全局配置对象 // DocumentationType：指定文档类型为swagger2 return new Docket(DocumentationType.SWAGGER_2) // swagger信息 .apiInfo(apiInfo()); } // swagger文档信息 public ApiInfo apiInfo() { // 作者信息 Contact contact = new Contact( // 文档发布者的名称 "iqiuq", // 文档发布者的网站地址 "https://iqiuq.gitee.io/qiuqblogs/", // 文档发布者的电子邮箱 "qiuyonghui258@163.com" ); return new ApiInfo( // 标题 "iqiuq swagger api", // 文档描述 "演好自己人生的剧本", // 版本号 "1.0", // 服务组url地址 "urn:tos", // 作者信息 contact, // 开源组织 "Apache 2.0", // 开源地址 "http://www.apache.org/licenses/LICENSE-2.0", // 集合 new ArrayList() ); } }
4.2 swagger扫描包配置
@Configuration @EnableSwagger2 //开启swagger2 public class SwaggerConfig { // 创建swagger bean @Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2) // swagger信息 .apiInfo(apiInfo()) // swagger 扫描包配置 // select()获取Docket中的选择器，返回ApiSelectorBuilder构造选择器，如扫描扫描包的注解 .select() /** * requestHandlerSelectors：请求处理选择器 * basePackage()：扫描指定包下的所有接口 * any()：扫描所有的包 * none()：不扫描 * withClassAnnotation()：扫描指定类上的注解，参数是一个注解的放射对象 * withMethodAnnotation()：扫描方法上的注解 */ // 指定扫描器扫描的规则（断言） .apis(RequestHandlerSelectors.basePackage("com.iqiuq.swaggerdemo.controller")) /** * pathSelectors：路径选择器，过滤路径 * ang()：选择所有路径 * none()：都不选择 * ant()：选择指定路径 * regex()：正则表达式 */ .paths(PathSelectors.regex("/hello")) .build(); } return new ApiInfo( // 标题 "iqiuq swagger api", // 文档描述 "演好自己人生的剧本", // 版本号 "1.0", // 服务组url地址 "urn:tos", // 作者信息 contact, // 开源组织 "Apache 2.0", // 开源地址 "http://www.apache.org/licenses/LICENSE-2.0", // 集合 new ArrayList() ); }
4.3 配置是否开启swagger
@Configuration @EnableSwagger2 //开启swagger2 public class SwaggerConfig { // 创建swagger bean @Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2) // swagger信息 .apiInfo(apiInfo()) // 配置是否开启swagger，若为false，则浏览器不能访问 .enable(false); } // swagger文档信息 public ApiInfo apiInfo() { // 作者信息 Contact contact = new Contact( "iqiuq", "https://iqiuq.gitee.io/qiuqblogs/", "qiuyonghui258@163.com"); return new ApiInfo( "iqiuq swagger api", "演好自己人生的剧本", "1.0", "urn:tos", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList()); } }
需求：开发和测试环境中开启swagger，其他环境不开启
@Configuration @EnableSwagger2 //开启swagger2 public class SwaggerConfig { // 创建swagger bean @Bean public Docket docket(Environment environment) { // 配置swagger的docket的bean实例 Profiles profiles = Profiles.of("dev","test"); // 通过environment.acceptsProfiles()判断是否指定的环境中，是，则为true boolean flag = environment.acceptsProfiles(profiles); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .enable(flag) .select() .apis(RequestHandlerSelectors.basePackage("com.iqiuq.swaggerdemo.controller")) .paths(PathSelectors.regex("/hello")) .build(); } // swagger文档信息 public ApiInfo apiInfo() { Contact contact = new Contact( "iqiuq", "https://iqiuq.gitee.io/qiuqblogs/", "qiuyonghui258@163.com"); return new ApiInfo( "iqiuq swagger api", "演好自己人生的剧本", "1.0", "urn:tos", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList()); } }
4.3 swagger分组配置
每个组就是一个docket实例，多个组就是创建多个docket的实例
@Configuration @EnableSwagger2 //开启swagger2 public class SwaggerConfig { // 创建swagger bean @Bean public Docket docket1(Environment environment) { // 配置swagger的docket的bean实例 Profiles profiles = Profiles.of("dev","test"); // 通过environment.acceptsProfiles()判断是否指定的环境中，是，则为true boolean flag = environment.acceptsProfiles(profiles); return new Docket(DocumentationType.SWAGGER_2) // swagger信息 .apiInfo(apiInfo()) // 配置是否开启swagger，若为false，则浏览器不能访问 .enable(flag) // 配置组名 .groupName("iqiuq") .select() .apis(RequestHandlerSelectors.basePackage("com.iqiuq.swaggerdemo.controller")) .paths(PathSelectors.regex("/hello")) .build(); } @Bean public Docket docket2(Environment environment) { Profiles profiles = Profiles.of("dev","test"); boolean flag = environment.acceptsProfiles(profiles); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .enable(flag) .groupName("哈哈哈") .select() .apis(RequestHandlerSelectors.basePackage("com.iqiuq.swaggerdemo.controller")) .paths(PathSelectors.regex("/hello")) .build(); } @Bean public Docket docket3(Environment environment) { Profiles profiles = Profiles.of("dev","test"); boolean flag = environment.acceptsProfiles(profiles); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .enable(flag) .groupName("嘻嘻嘻") .select() .apis(RequestHandlerSelectors.basePackage("com.iqiuq.swaggerdemo.controller")) .paths(PathSelectors.regex("/hello")) .build(); } // swagger文档信息 public ApiInfo apiInfo() { Contact contact = new Contact( "iqiuq", "https://iqiuq.gitee.io/qiuqblogs/", "qiuyonghui258@163.com"); return new ApiInfo( "iqiuq swagger api", "演好自己人生的剧本", "1.0", "urn:tos", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList()); }
注意：
如果你使用的是swagger 3.0 你就需要使用 <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>3.0.0</version> </dependency> 访问：http://localhost:8080/swagger-ui/index.html 就可以实现swagger-ui.html的访问
五、swagger常用注解
swagger注解主要是用来给swagger生成的接口文档说明用的
5.1 @Api
- @Api：是类上注解，控制整个类生成接口信息的内容
- tags：类的名称，可以有多个值，多个值表示多个副本，在UI视图中就显示几个控制器访问菜单
- description：描述，已过时
5.2 @ApiOperation
- @ApiOperation：方法的说明，value值必须提供
- value：说明方法的作用
- notes：方法的备注说明
5.3 @ApiParam
- @ApiParam：可以作用于方法参数和成员变量
- name：参数别名
- value：参数的描述
- required：是否必须需要
5.4 @ApiIgnore
- @Apilgnore：忽略，当前注解描述的方法或类型，不生成api文档
5.5 @ApiImplicitParam和@ApiImplicitParams
- @ApiImplicitParam：使用在方法上，描述方法的单个参数
- name：参数名称
- value：描述
- required：是否必要参数
- paramType：参数类型
- dataType：数据类型
- @ApiImplicitParams：使用在方法上，描述方法的一组参数
- value：是@ApiImplicitParam类型的数组
- value：是@ApiImplicitParam类型的数组
5.6 @ApiModel和@ApiModelProperty
- @ApiModel：描述一个实体类型，这个实体类型如果成为任何一个生成api帮助文档方法的一个返回值类型的时候，此注解被解析
- value：自定义实体
- description：详细描述
- @ApiModelProperty：实体类属性描述
- name：字段别名
- value：字段描述
- required：是否是必须字段
- example：示例数据
- hidden：是否隐藏数据
5.7 @ApiResponse和@ApiResponses
@ApiResponses、@ApiResponse方法返回值的说明
- @ApiResponses：方法返回对象的说明
- @ApiResponse：每个参数的说明
- code：数字，例如：300
- message：信息，例如：”请求参数没填好"
- response：抛出异常的类
5.8 其他注解
- @Authorization：声明要在资源或操作上使用的授权方案
- @AuthorizationScope：描述OAuth2授权范围
- @ResponseHeader：表示可以作为响应的一部分提供的标头
- @ApiProperty：描述POJO对象中的属性值
- @ApiError：接口错误所返回的信息
六、总结
- 我们可以通过swagger给一些比较难理解的属性或接口，增加注释信息
- 接口文档实时更新
- 可以在线测试
- 在正式发布的时候，关闭swagger，出于安全考虑，而且节省内存
分类:
Java
标签:
swagger
, springboot
【推荐】国内首个AI IDE，深度理解中文开发场景，立即下载体验Trae
【推荐】编程新体验，更懂你的AI，立即体验豆包MarsCode编程助手
【推荐】抖音旗下AI助手豆包，你的智能百科全书，全免费不限次数
【推荐】轻量又高性能的 SSH 工具 IShell：AI 加持，快人一步
· 从 HTTP 原因短语缺失研究 HTTP/2 和 HTTP/3 的设计差异
· AI与.NET技术实操系列：向量存储与相似性搜索在 .NET 中的实现
· 基于Microsoft.Extensions.AI核心库实现RAG应用
· Linux系列：如何用heaptrack跟踪.NET程序的非托管内存泄露
· 开发者必知的日志记录最佳实践
· TypeScript + Deepseek 打造卜卦网站：技术与玄学的结合
· Manus的开源复刻OpenManus初探
· AI 智能体引爆开源社区「GitHub 热点速览」
· C#/.NET/.NET Core技术前沿周刊 | 第 29 期（2025年3.1-3.9）
· 从HTTP原因短语缺失研究HTTP/2和HTTP/3的设计差异