SpringBoot中集成Swagger2及简单实用
作者：秋天code
介绍
Swagger是非常流行的API框架，能够自动生成RESTFul 风格的API文档，还可以在线测试后台接口。
使用Swagger你只需要按照它的规范去定义接口及接口相关的信息，再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，以及在线接口调试页面等等。
前后端分离的开发模式下，前端通过后端的API文档来进行开发和联调，效率更高。
Swagger就是帮助后端生成API文档的工具
简单使用
在SpringBoot中集成Swagger2，（等会说一个更简单的用法）。
引入依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>配置类
@Configuration
@EnableSwagger2
public class Swagger2Config {
/**
* 将负责生成摘要的Bean提供出去
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//是否开启 (true 开启 false隐藏。生产环境建议隐藏)
//.enable(false)
.select()
//扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
.apis(RequestHandlerSelectors.basePackage("com.liumingkai.controller"))
//指定路径处理PathSelectors.any()代表所有的路径
.paths(PathSelectors.any())
.build();
}
/**
* 用来设置文档元信息
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//设置文档标题(API名称)
.title("SpringBoot中使用Swagger2接口规范")
//文档描述
.description("接口说明")
//版本号
.version("1.0.0")
.build();
}
}使用
因为Swagger帮助我们生成RestFul风格的文档，所以被修饰的接口方法必须是类似于@GetMapping、@PostMapping、@DeleteMapping，不能是一个笼统的@RequestMapping
下面会有详细的常用注解说明，此处只是想要来快速看一下效果
@RestController
@RequestMapping("/user")
@Api(value = "测试接口", tags = "用户登录接口")
public class LoginController {
@PostMapping("/login")
@ApiOperation(value = "登录", tags = "登录接口")
public String login(String username, String password){
return "登录成功"+username+password;
}
@PostMapping("/logout")
@ApiOperation(value="退出登录",tags = "退出登录")
public String logout(String username){
return "退出登录成功";
}
}接下来访问http://ip:port/swagger-ui.html，会看到
SpringBoot版本与Swagger版本的冲突问题
如果你访问Swagger的文档地址后，发现是404，无法访问，那么大概是SpringBoot的版本问题
注意：
如果你的SpringBoot是2.6.x及更高，那么与Swagger2是不兼容的，因为SpringMVC的处理映射匹配的方式发生了变化。
需要在SpringBoot的配置文件中通过添加配置来使springboot2.6.x以后的版本来适配Swagger2
不要试图通过@EnableWebMvc来解决，同样会导致404
spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher常用注解
Swagger的核心就是我们常用的这几个注解
@Api
一般用来标注在Controller上，注意此Controller要是一个RestController。
| 注解 | 说明 |
|---|---|
| @Api | 一般用在Controller类上，Swagger会扫描被此注解标注的类，并生成一个文档分类 |
| @ApiOperation | 用在接口方法上，对该接口方法进行描述 |
| @ApiModel | 用在实体类上，为此实体类生成说明文档 |
| @ApiParam | 用来接口参数上，用来对此请求参数做说明 |
| @ApiModelProperty | 用来实体类中的属性上，对此属性做说明 |
@RestController
@RequestMapping("/user")
@Api(value = "测试接口", tags = "用户登录接口")
public class LoginController {
}属性：
- value ， 该接口模块的名称，没啥用，对于程序员来说起一个标识作用
- tags，该接口模块在文档中的标签名，会在API文档中显示。
- 如果未指定此模块的tags标签，那么就会使用Controller的类名作为tags名称
- tags可以认为是一个分类，名称相同的内容，会被归为一个分类。
- hidden，隐藏该模块，默认是false，不隐藏，隐藏后该模块不会出现在api文档中
@ApiOperation
次注解用在方法上，对该接口进行描述。
@RestController
@RequestMapping("/user")
@Api(value = "测试接口", tags = "用户登录接口")
public class LoginController {
@PostMapping("/login")
@ApiOperation(value = "登录", tags = "用户登录接口")
public String login(String username, String password){
return "登录成功"+username+password;
}
@PostMapping("/logout")
@ApiOperation(value="退出登录",tags = "用户登录接口")
public String logout(String username){
return "退出登录成功";
}
}属性：
- value，该接口方法的名称，必填的属性，用来对接口标识作用
- tags，用来指定该接口属于的标签，tags相同的接口方法，在文档中会属于同一个分类下
- 一个接口方法可以属于多个分类
- hidden，是否隐藏该接口，默认是false
@ApiParam
用在接口的参数上，用来对该参数进行修饰
属性：
- value，标识作用
- name，该参数的名称，如果省略该属性，则会以参数名来作为名称在文档中显示
- required，是否必选，默认是false，此属性最常用
@RestController
@RequestMapping("/user")
@Api(value = "测试接口", tags = "用户登录接口")
public class LoginController {
@PostMapping("/login")
@ApiOperation(value = "登录", tags = "用户登录接口")
public String login(@ApiParam(name="username", required = true) String username, @ApiParam(name="password",required = true) String password){
return "登录成功"+username+password;
}
@PostMapping("/logout")
@ApiOperation(value="退出登录",tags = "用户登录接口")
public String logout(String username){
return "退出登录成功";
}
}
@ApiResponse
用在方法上，对接口的返回内容进行描述
常用属性：
- code，响应的状态码
- message，返回的描述信息
- response，用来指定返回的实体类，也就是真正的响应数据
@GetMapping("/detail/{username}")
@ApiOperation("获取用户详情信息")
@ApiResponse(code = 200,message = "查询成功",response = User.class)
public User getDetail(@ApiParam(value = "要查询的用户名", required = true) @PathVariable("username") String username) {
User user = new User();
user.setAge(18);
user.setUsername("zhagnsan");
user.setPassword("123156");
user.setSex("男");
return user;
}@ApiResponses
如果返回的结果有多种，则可以使用@ApiResponses注解，此注解只有一个属性value，是一个@ApiResponse的数组。
其中包含多个@ApiResponse，每个@ApiResponse都是一种响应结果
@GetMapping("/detail/{username}")
@ApiOperation("获取用户详情信息")
@ApiResponses({
@ApiResponse(code = 200, message = "成功", response = User.class),
@ApiResponse(code = 403, message = "你还没有权限")
}
)
public User getDetail(@ApiParam(value = "要查询的用户名", required = true) @PathVariable("username") String username) {
User user = new User();
user.setAge(18);
user.setUsername("zhagnsan");
user.setPassword("123156");
user.setSex("男");
return user;
}@ApiModel
- 用在实体类上，用来对此实体类进行描述。
- 如果你的返回值类型或参数类型是实体类类型，那么Swagger就会使用@ApiModel对其进行描述
属性：
value，标识名，如果不填，则会以类名作为valuedescription，类的描述信息
实体类上标注了此类后，会将所有的属性进行描述
@ApiModel(value="用户实体类",description = "这是返回的实体类的描述信息")
@Data
public class User {
private String username;
private String password;
private String sex;
private Integer age;
}一般都是直接@ApiModel注解，不用属性
@ApiProperty
如果需要对实体类中的属性进行单独的设置，那么就需要使用@ApiProperty属性了
常用属性：
- value，标识
- name，名称，在文档中的显示的名称
- hidden，是否隐藏此属性
- required，此属性是否必须
@ApiModel(value="用户实体类",description = "这是返回的实体类的描述信息")
@Data
public class User {
@ApiModelProperty(value = "用户名",required = true)
private String username;
@ApiModelProperty(hidden = true)
private String password;
private String sex;
private Integer age;
}
参考文档：
SpringBoot与Swagger2版本不兼容的问题！！
Failed to start bean ‘documentationPluginsBootstrapper‘； nested exception is java.lang.NullPointerEx_Shipley_Leo的博客-CSDN博客
Springboot ✚ Swagger各版本整理_swaager 版本_qq_33334411的博客-CSDN博客
swagger-ui.html页面无法打开解决方案_Alphathur的博客-CSDN博客
到此这篇关于SpringBoot中集成Swagger2的文章就介绍到这了,更多相关SpringBoot集成Swagger2内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！