2025年swagger2作用（swagger2 ui）

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

 <p></p>

讯享网

1、可以生成接口文档

2、可以进行接口测试，像postman一样

1、导入依赖

讯享网

springfox-swagger2：核心依赖，用来生成接口文档

讯享网springfox-swagger-ui：制作网页文档

一般两个一起放在controller层中

如果实体类或者VO类是独立模块，可以把springfox-swagger2放到实体类的pom文件中

2、配置类

复制过来修改下面这句里的controller包名就行，直接用

讯享网

上面两步做完，已经可以使用了，但是生成的文档是英文的，下面的注解只是把英文显示成中文，可以不看了

3、打开接口文档

启动项目，然后在网页里打开网址：http://localhost:8080/swagger-ui.html

显示如下

讯享网

goods-controller和user-controller 可以展开查看里面的方法了

每个方法还可以继续展开，这里点开addGoods，显示下面的内容

点开的方向里，可以直接填参数发请求测试接口

4、测试请求

点开user-controller里的login方法

返回结果如下，还是很详细的

上面就是使用方法

然后就是一些注解，用来把页面里的英文改成中文

1、Api

加个controller类上面

显示效果

2、ApiOperation

方法描述，放在方法上面

讯享网

显示效果如下

3、ApiImplicitParams和ApiImplicitParam

参数描述，写在方法上

多个参数：

单个参数：

讯享网

如果参数是实体类的话，可以不用写，而且直接在实体类上加注角

4、ApiModel

写在实体类上

5、ApiIgnore

讯享网

写在方法上，添加此注解的方法不会出现在文档中

基本内容就这些了

光使用的话只要加依赖，加配置类，知道打开的地址就行了

在controller层导入依赖就行

打开网址是：http://localhost:8080/doc.html

显示效果比原界面好看点

上面的配置换了台电脑使用，一直报：

Failed to start bean ‘documentationPluginsBootstrapper’

百度了好几天，今天终于解决了，方法如下

配置类要继承 WebMvcConfigurationSupport

继承完，发请求还报：

: No mapping for GET /swagger-ui.html

这是找不到静态资源，本来直接可以用的，现在继承了webmvc，出来了新问题，所以再重新配置静态资源，顺便加上/META-INF/resources/ 文件夹

讯享网

到这为止

http://localhost:8080/swagger-ui.html 可以正常打开了

但是 http://localhost:8080/doc.html 打不开了

最后还是回到最开始，很幸运，第一次使用swagger2的时候是成功的

我把原来的代码翻出来，所有依赖的版本都对照着改了一下

最终发现，springboot 2.5.7 才能和 swagger2 2.9.2 一起使用

这星期都在折腾swagger2上了，要不是第一次走狗屎运导入了2.5.7的springboot，下个星期，下下个星期可能都找不到问题出在哪

下面放个依赖，以后直接复制，swagger2和springboot无冲突版本

如果有把实体类当参数，还会报下面这个错

讯享网

原因是io.swagger.models.parameters.AbstractSerializableParameter会实例化参数，也就是通过example的值为属性赋值，如果example没有显式的赋值，就是空串“”，但是如果实体类用作application/json那么就不会走这个方法去实例化参数。

按照这个原因描述，解决方法就是三个了

第一个解决方法：直接替换替换swagger中的model依赖，这个算是bugger，在下一个版本中已经解决了，默认是1.5.20版，换成1.5.21就行

第二个解决方法：手动用example来赋值，只需要给整型参数赋值就行了，就像下面的userId

讯享网

第三个解决方法：把实体类当成application/json格式