SpringBoot项目中使用Swagger2,及其详细介绍注解
文章目录
什么是swagger2
编写和维护接口文档是每个程序员的职责,根据Swagger2可以快速帮助我们编写最新的API接口文档,再也不用担心开会前仍忙于整理各种资料了,间接提升了团队开发的沟通效率。
1、swagger2的配置
1.1、引入Swagger2依赖
<!--swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<!--swagger ui-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
<!--swagger2 增强版接口文档-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.4</version>
</dependency>
1.2、编写SwaggerConfig配置文件
package com.melody.rest.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;
/**
* @ClassName: SwaggerConfig
* @Description: Swagger配置了类
* @Author: liu-hao
* @Date: 2020-12-10 10:18
* @Version: 1.0
**/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
// api接口包扫描路径
public static final String SWAGGER_SCAN_BASE_PACKAGE = "com.melody.rest.restcontroller";
// 接口文档版本
public static final String VERSION = "1.0.0";
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
//用于分组功能,也可以不配置
.groupName("eleprice-service")
//注册整体api信息
.apiInfo(apiInfo())
//swagger功能是否启用,可以通过配置设置,也可以先写死
.enable(true)
.select()
.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("学习系统")
.description("接口文档")
.contact(new Contact("张三", "http://liushili.icu", "xxxxx@163.com"))
.version(VERSION)
.build();
}
}
注意:更改成项目中的controller
1.3、配置类及其参数说明
(1)创建Docker类型的对象,并使用spring容器管理。Docker是Swagger中的全局配置对象
DocumentationType.SWAGGER_2:给Docket一个类对象,知道是那一个版本的
apiInfo():API文档的描述信息,参数是一个ApiInfo类对象,使用bulid()构建器来创建
private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("平台接口 v1.0") .description("平台接口") .contact(contact) .version("1.0") .build(); } 12345678
(2)contact():配置swagger文档的主体内容,里面填写也是一个类对象,类对象最多可以三个参数,发布者名称,文档发布者的网站url地址(企业网站),文档发布者的电子邮箱地址
private Contact contact = new Contact("NIUA","localhost:8080/swagger-ui.html", "1053288979@qq.com");
1
title():标题 description():描述信息 .version():版本信息
对应如下内容
select():获取Docker中的选择器,返回ApiSelectorBuilder。构建选择器。如扫描什么包的注解
apis():后面是RequestHandlerSelectors的类下的(Predicate)规则,规定扫描那些包的注解,默认是启动类及其子包下的注解
RequestHandlerSelectors类下有几个静态方法(举例三个)
basePackage():后面填写包名的具体地址,会扫描改包及其子包的注解
docker.apis(RequestHandlerSelectors.basePackage("com.xxx")) 1
any():为任何接口生成API文档
none():任何接口都不生成接口文档
path():使用正则表达式,约束生成Api文档的路径地址,后面填写过滤(通过)的路径
//过滤掉admin路径下的所有页面
.paths(Predicates.not(PathSelectors.regex("/admin/.*")))
//过滤掉所有error或error.*页面
.paths(Predicates.not(PathSelectors.regex("/error.*")))
//所有error或error.*页面或者admin路径下的所有页面都支持(or任意满足起一就通过)
.paths(Predicates.or(PathSelectors.regex("/error.*"),PathSelectors.regex("/admin/.*")))
2、swagger2 注解整体说明
2.1、请求类的描述
注解 | 说明 |
---|---|
@Api | 对请求类的说明 |
2.2、方法和方法参数的描述
注解 | 说明 |
---|---|
@ApiOperation | 方法的说明 |
@ApiImplicitParams | 方法参数的说明; |
@ApiImplicitParam | 用于指定单个参数的说明。 |
2.3、方法的响应状态的描述
注解 | 说明 |
---|---|
@ApiResponses | 方法返回值的说明 ; |
@ApiResponse | 用于指定单个参数的说明。 |
2.4、对象的描述
注解 | 说明 |
---|---|
@ApiModel | 用在JavaBean类上,说明JavaBean的 整体用途 |
@ApiModelProperty | 用在JavaBean类的属性上面,说明此属性的的含议 |
3、请求类的描述
3.1、@Api:请求类的说明
@Api:放在 请求的类上。与 @Controller 并列,说明类的作用,如用户模块,订单类等。
tags="说明该类的作用"
value="该参数没什么意义,所以不需要配置"
123
3.2、示例:
@Api(tags="订单模块")
@Controller
public class OrderController {
}
12345
@Api
其它属性配置:
属性名称 | 备注 |
---|---|
value | url的路径值 |
tags | 如果设置这个值、value的值会被覆盖 |
description | 对api资源的描述 |
basePath | 基本路径 |
position | 如果配置多个Api 想改变显示的顺序位置 |
produces | 如, “application/json, application/xml” |
consumes | 如, “application/json, application/xml” |
protocols | 协议类型,如: http, https, ws, wss. |
authorizations | 高级特性认证时配置 |
hidden | 配置为true ,将在文档中隐藏 |
4、方法和方法参数的描述
4.1、@ApiOperation:方法的说明
@ApiOperation:"用在请求的方法上,说明方法的作用"
value="说明方法的作用"
notes="方法的备注说明"
123
4.2、@ApiImplicitParams、@ApiImplicitParam:方法参数的说明
@ApiImplicitParams:用在请求的方法上,包含一组参数说明
@ApiImplicitParam:对单个参数的说明
name:参数名
value:参数的说明、描述
required:参数是否必须必填
paramType:参数放在哪个地方
· query --> 请求参数的获取:@RequestParam
· header --> 请求参数的获取:@RequestHeader
· path(用于restful接口)--> 请求参数的获取:@PathVariable
· body(请求体)--> @RequestBody User user
· form(普通表单提交)
dataType:参数类型,默认String,其它值dataType="Integer"
defaultValue:参数的默认值
4.3、示列:
@Api(tags="用户模块")
@Controller
public class UserController {
@ApiOperation(value="用户登录",notes="这里是备注")
@ApiImplicitParams({
@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
@PostMapping("/login")
public JsonResult login(@RequestParam String mobile, @RequestParam String password, @RequestParam Integer age){
//...
return JsonResult.ok(map);
}
}
5、对象的描述
5.1、@ApiModel:对象的整体说明
@ApiModel
经常用于请求的入参对象和 响应返回值对象的描述。
- 入参是对象,即
@RequestBody
时, 用于封装请求(包括数据的各种校验)数据; - 返回值是对象,即
@ResponseBody
时,用于返回值对象的描述。
@ApiModel(description = "用户登录")
public class UserLoginVO implements Serializable {
}
1234
5.2、@ApiModelProperty 对象中每个参数的说明
@ApiModelProperty 用于每个属性上面,说明属生的含义。
@ApiModel
public class UserLoginVO implements Serializable {
@ApiModelProperty(value = "用户名",required=true)
private String username;
}
123456
5.3、示例:
入参是对象,即 @RequestBody
时, 用于封装请求
@ApiModel(description = "用户登录")
public class UserLoginVO implements Serializable {
private static final long serialVersionUID = 1L;
@ApiModelProperty(value = "用户名",required=true)
private String username;
@ApiModelProperty(value = "密码",required=true)
private String password;
// getter/setter省略
}
ApiModel(description = "用户登录")
public class UserLoginVO implements Serializable {
private static final long serialVersionUID = 1L;
@ApiModelProperty(value = "用户名",required=true)
private String username;
@ApiModelProperty(value = "密码",required=true)
private String password;
// getter/setter省略
}