2025年swagger2配置文件（swagger2config）

大家好，我是讯享网，很高兴认识大家。

 <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <path stroke-linecap="round" d="M5,0 0,2.5 5,5z" id="raphael-marker-block" style="-webkit-tap-highlight-color: rgba(0, 0, 0, 0);"></path> </svg> <blockquote>

讯享网

在目前前后端分离的模式中无论是前端开发还是后端开发基本上都被文档折磨过，前端开发经常会遇到后端接口改变，调整等文档未及时更新问题，而后端开发又会在文档的编写与维护上耗费大量的精力。

平时手写文档出现的问题：

文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
接口返回结果不明确
不能直接在线测试接口，通常需要使用工具，比如：
接口文档太多，不好管理

市场既然有需求，那么肯定就会有方案。解决方案多了就行成了标准，这就是Swagger的由来。

根据官网的介绍，Swagger是一系列用于Restful API开发的工具，开源的部分包括：

：API规范，规定了如何描述一个系统的API
：用于通过API规范生成服务端和客户端代码
：用来编写API规范
：用于展示API规范

我们目前在开发使用的主要是Springfox Swagger，Springfox 是一个通过扫描代码提取代码中的信息，生成API文档的工具。在Swagger的教程中的都会提到的，，等这些注解并不是Springfox的，而是Swagger的，Spring-swagger2这个包依赖了swagger-core，而这些注解是swagger-core里面的。但是swagger-core这个包只支持JAX-RS2，而不支持我们常用的Spring MVC，而Springfox 就是把这些适用于JAX-RS2中的注解适配到Spring MVC上。所以springfox 又可以称之为swagger2，swagger的二代

在pom.xml文件中加入

讯享网

添加了一个bootstrap框架的ui，更直观访问地址是http://localhost:端口号/doc.html

Application 中加上注解表示开启 Swagger

Swagger常用注解

1. @Api，用在请求的类上，表示对类的说明

（1）tags=“说明该类的作用，可以在UI界面上看到的注解”

（2）value=“该参数没什么意义，在UI界面上也看不到，所以不需要配置”

讯享网

2. @ApiOperation：用在请求的方法上，说明方法的用途、作用

（1）value=“说明方法的用途、作用”

（2） notes=“方法的备注说明”

3. @ApiImplicitParams：用在请求的方法上，表示一组参数说明

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

讯享网

（1） name：参数名

（2）value：参数的汉字说明、解释

（3）required：参数是否必须传

（4）paramType：参数放在哪个地方

· header –> 请求参数的获取：@RequestHeader

· query –> 请求参数的获取：@RequestParam

· path（用于restful接口）–> 请求参数的获取：@PathVariable

· body（不常用）

· form（不常用）

（5）dataType：参数类型，默认String，其它值dataType=“Integer”

（6）defaultValue：参数的默认值

讯享网

4.@ApiParam：用在方法的参数中

（1）name : 参数名字
（2）value：参数说明
（3）required：是否为非必传 true必传 false非必传
（4）type：参数类型

5. @ApiResponses：用在请求的方法上，表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

（1）code：数字，例如400
（2）message：信息，例如“请求参数没填好”
（3）response：抛出异常的类

讯享网

1. @ApiModel：用于响应类上，表示一个返回响应数据的信息

2. @ApiModelProperty 用在属性上，描述响应类的属性

讯享网