大家好,我是你们的梵哥, 今天和大家来聊一下SpringBoot如何整合swagger.话不多说。
第一步. 引入JAR，我选用的是2.9.2，若选用其他版本，注意JAR之间的问题。
<!-- swagger -->
<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>
第二步. 引入JAR后就可以编写swagger配置类了，配置详解和swagger的注解可以查阅其他资料，为避免篇幅太长这里就不多解释啦。以下是config类代码。
package com.farm.fowl.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* <p></p>
*
* @author : YYF
* @Description TODO
* @date : 2021-04-10 14:17
**/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
//apiInfo指定测试文档基本信息，这部分将在页面展示
.apiInfo(apiInfo())
.select()
//控制哪些接口暴露给swagger，
// RequestHandlerSelectors.any() 所有都暴露
// swagger加载指定包路径
.apis(RequestHandlerSelectors.basePackage("com.farm.fowl.controller"))
.paths(PathSelectors.any())
.build();
}
//基本信息，页面展示
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("五七塘家禽养殖项目")
.description("涛哥好威风")
//联系人实体类
.contact(
new Contact("没得梵哥威风", "www.baidu.com", "495029893@qq.com")
)
//版本号
.version("1.0.0")
.build();
}
}
第三步. 编写请求返回model.这里为了测试我就用同一个了。
package com.farm.fowl.vo;
import com.farm.fowl.util.model.ToString;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
/**
* @author YYF
*/
@Data
@ApiModel(value = "UserInfo", description = "用户信息")
public class UserInfo extends ToString {
@ApiModelProperty(value = "id", example = "123", name = "用户ID", required = true)
private Integer id;
@ApiModelProperty(value = "userName", example = "张三", name = "用户姓名", required = true)
private String userName;
}
关于@ApiModel @ApiModelProperty这两个注解主要作用是为swagger后续读取这些信息。具体就不说啦，这个大家应该一看就会需要注意的是 @ApiModel注解里 value = "UserInfo" 这个value的值最好跟类名保持一致，原因我下面会提到。
第四步. 编写controller类，注意，这个类路径一定要在上面config扫描的包路径下。
package com.farm.fowl.controller.swagger;
import com.farm.fowl.vo.UserInfo;
import com.farm.fowl.vo.swagger.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
/**
*
* @author : YYF
* @Description TODO
* @date : 2021-04-10 13:29
**/
@Api("用户管理api")
@RestController
@RequestMapping("/userApi")
public class UserApiController {
/**
* 用户登陆
*
* @return
*/
@PostMapping(value = "/login")
//方法参数说明，name参数名；value参数说明，备注；dataType参数类型；required 是否必传；defaultValue 默认值
@ApiImplicitParams(value = {@ApiImplicitParam(name = "userInfo", value = "UserInfo", paramType = "body", dataType = "UserInfo", required = true)
})
//说明是什么方法(可以理解为方法注释)
@ApiOperation(value = "添加用户", notes = "添加用户")
public UserInfo login(@RequestBody UserInfo userInfo) {
return new UserInfo();
}
/**
* 通过id查询用户
* @return
*/
@GetMapping(value = "/getUser")
@ApiImplicitParam(name = "code", value = "用户code", defaultValue = "123456", dataType = "String", required = true)
public User getUserByCode(String code) {
return new User();
}
}
现在所有准备工作搞定，先来看看效果。
启动项目，打开 http://localhost:8080/swagger-ui.html# （端口跟随自己项目变动）。看到下面这个就代表成功了。
现在打开GET方法，看看里面有些什么。
这是返回类POJO
点击上面箭头Try it out 可以进行请求发起测试，箭头指向填请求参数。
填好自己的请求参数，点击Execute，然后查看response.
现在再来看看post请求 ，点击Example Value 与Model 切换查看模式
可以看到请求的默认参数（默认JSON格式）就是我们刚刚在POJO @ApiModelProperty注解的example的值。同样，点击Try it out 可对报文进行修改，然后执行。
--------------------------------整合就聊到这-------------------------------------
现在我们来聊一聊整合过程中可能遇到的坑。
- 请求model必须要有get/set方法(我用的是@Data注解，用@Data需注意你的IDE有没有安装lombok插件,并且把Hrisey Plugin插件关掉，不然使用get/set方法时IDE会告警)，因为没有get/set方法不只是没法赋值,@ApiModelProperty注解也不会生效（因为属性私有），可以自己试试效果。
-
@ApiModel注解的值尽量与类名一致,这是因为当使用POST请求，并且请求参数为对象时@ApiImplicitParam注解 dataType = "类名"，如@ApiImplicitParam(name = "userInfo", value = "UserInfo", paramType = "body", dataType = "UserInfo", required = true)
post请求paramType为body(get请求可选默认)时，dataType为对应接受参数的model，它是根据model中@ApiModel(value = "UserInfo")注解中value的值找对应的类若不一致，会加载不到对应的请求Model，导致swagger解析失败。
swagger5.png
最后附上swagger几个注解的含义
1、@Api(value = "", description = "")
此注解应用在类上面，表示对类的说明。其中，
（1）tags="说明该类的作用，可以在UI界面上看到的注解" （非空时将覆盖value的值）
（2）value="说明类的作用"
（3）description="说明类的作用，对类的作用进行描述"（1.5版本后将不在支持）
2、@ApiOperation(notes = "", value = "")
此注解作用在方法上面，说明该方法的用途等
（1）value="说明该方法的作用和用途"
（2）notes="对该方法的备注信息说明"
3、@ApiImplicitParams
此注解作用在类上，表明对一组参数的说明
@ApiImplicitParam 用在@ApiImplicitParams注解的内部，表明对一组参数的各个方面进行具体的说明
（1）name参数名
（2）value对参数的说明
（3）required参数是否必传（值为true或者false）
（4）dataType参数类型，默认是String，其他例如：Integer
（5）paramType 参数放在什么地方
· header --> 请求参数的获取：@RequestHeader ·
query --> 请求参数的获取：@RequestParam ·
path（用于restful接口）--> 请求参数的获取：@PathVariable ·
body 以流的形式提交 仅支持POST
form（不常用）
4、@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse用在@ApiResponses中，常用于表示一组错误的信息的响应
（1）code错误代码
（2）massege错误信息提示
（3）response 抛出异常的类
示例：
@ApiResponses({
@ApiResponse(code=400,message="请求参数没填好"),
@ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
})
5、@ApiParam用在请求方法中，描述参数的信息
name参数名称，参数名称可以覆盖方法参数名称，路径参数必须与方法参数一致
value参数的简要说明。
defaultValue参数默认值
required 属性是否必填，默认为false [路径参数必须填]
示例：
@ResponseBody
@PostMapping(value="/login")
@ApiOperation(value = "登录检测", notes="根据用户名、密码判断该用户是否存在")
public UserModel login(@ApiParam(name = "name", value = "用户名", required = false)
@RequestParam(value = "name", required = false) String account,
@ApiParam(name = "pass", value = "密码", required = false) @RequestParam(value = "pass", required = false) String password){}
6、@ApiIgnore用在类或者方法上，表明在swagger2中忽略这个类或者方法或者参数。
