SpringBoot整合Swagger2以及相关知识点详解

在上一篇记录了SpingBoot使用Restful风格实现增删改查 &＃xff0c;所以我们就在上一篇代码的基础上实现本节内容。因为现在很多都是前后端分离&＃xff0c;所以有一份合理高效的API文档就很重要。虽然苦B的我平时项目中前后端都是自己做&＃xff0c;但是该学的还是得学啊。好了&＃xff0c;进入主题。

一、pom.xml

io.springfoxspringfox-swagger22.9.2io.springfoxspringfox-swagger-ui2.9.2

二、Swagger2配置类

在启动类的同目录下创建Swagger2的配置类

&＃64;Configuration
&＃64;EnableSwagger2
public class Swagger2 {&＃64;Beanpublic Docket createRestApi(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() // 选择那些路径和api会生成document.paths(PathSelectors.any()).apis(RequestHandlerSelectors.any())// 对所有api进行监控.apis(RequestHandlerSelectors.basePackage("com.example.restfuldemo.controller")).build().securitySchemes(security());}/*** 接口文档详细信息** &＃64;return*/private ApiInfo apiInfo() {return new ApiInfoBuilder().title("这是我的接口文档").contact(new Contact("LoneWalker", "", "LoneWalker&＃64;163.com")).description("这是SWAGGER_2生成的接口文档").version("v1.0").build();}private List security() {ArrayList apiKeys &＃61; new ArrayList<>();apiKeys.add(new ApiKey("token", "token", "header"));return apiKeys;}
}


三、在类和方法上加上相关注解

&＃64;Api(tags &＃61; "用户信息接口")
&＃64;RestController
&＃64;RequestMapping("/api/user")
public class UserInfoController {&＃64;AutowiredUserInfoService userInfoService;&＃64;ApiOperation("添加用户信息")&＃64;PostMappingpublic int addUser(UserInfo userInfo){return userInfoService.addUser(userInfo);}&＃64;ApiOperation("更新用户信息")&＃64;PutMappingpublic int updateUser(UserInfo userInfo){return userInfoService.updateUser(userInfo);}&＃64;ApiOperation("删除用户信息")&＃64;DeleteMappingpublic int delUser(int id){return userInfoService.delUser(id);}&＃64;ApiOperation("获取所有用户")&＃64;GetMapping("/userAll")public List findAll(){return userInfoService.findAll();}}

&＃64;ApiModel(value &＃61; "用户类")
public class UserInfo implements Serializable {&＃64;ApiModelProperty(value &＃61; "ID", example &＃61; "1")private Integer id;&＃64;ApiModelProperty("用户真实姓名")private String name;&＃64;ApiModelProperty("密码")private String password;&＃64;ApiModelProperty("盐值")private String salt;&＃64;ApiModelProperty("状态")private String state;&＃64;ApiModelProperty("用户账号")private String username;

运行项目&＃xff0c;测试访问&＃xff1a;http://localhost:8080/swagger-ui.html

四、相关知识点记录

4.1常用注解

&＃64;Api&＃xff1a;用在请求的类上&＃xff0c;表示对类的说明tags&＃61;"说明该类的作用&＃xff0c;可以在UI界面上看到的注解"value&＃61;"该参数没什么意义&＃xff0c;在UI界面上也看到&＃xff0c;所以不需要配置"&＃64;ApiOperation&＃xff1a;用在请求的方法上&＃xff0c;说明方法的用途、作用value&＃61;"说明方法的用途、作用"notes&＃61;"方法的备注说明"&＃64;ApiImplicitParams&＃xff1a;用在请求的方法上&＃xff0c;表示一组参数说明&＃64;ApiImplicitParam&＃xff1a;用在&＃64;ApiImplicitParams注解中&＃xff0c;指定一个请求参数的各个方面name&＃xff1a;参数名value&＃xff1a;参数的汉字说明、解释required&＃xff1a;参数是否必须传paramType&＃xff1a;参数放在哪个地方· header --> 请求参数的获取&＃xff1a;&＃64;RequestHeader· query --> 请求参数的获取&＃xff1a;&＃64;RequestParam· path&＃xff08;用于restful接口&＃xff09;--> 请求参数的获取&＃xff1a;&＃64;PathVariable· body&＃xff08;不常用&＃xff09;· form&＃xff08;不常用&＃xff09; dataType&＃xff1a;参数类型&＃xff0c;默认String&＃xff0c;其它值dataType&＃61;"Integer" defaultValue&＃xff1a;参数的默认值&＃64;ApiResponses&＃xff1a;用在请求的方法上&＃xff0c;表示一组响应&＃64;ApiResponse&＃xff1a;用在&＃64;ApiResponses中&＃xff0c;一般用于表达一个错误的响应信息code&＃xff1a;数字&＃xff0c;例如400message&＃xff1a;信息&＃xff0c;例如"请求参数没填好"response&＃xff1a;抛出异常的类&＃64;ApiModel&＃xff1a;用于响应类上&＃xff0c;表示一个返回响应数据的信息&＃xff08;这种一般用在post创建的时候&＃xff0c;使用&＃64;RequestBody这样的场景&＃xff0c;请求参数无法使用&＃64;ApiImplicitParam注解进行描述的时候&＃xff09;&＃64;ApiModelProperty&＃xff1a;用在属性上&＃xff0c;描述响应类的属性

4.2 提示

&＃64;ApiModelProperty描述Integer类型参数时&＃xff0c;不加example会报

java.lang.NumberFormatException: For input string: ""