详细介绍注解"/>
SpringBoot项目中使用Swagger2,及其详细介绍注解
SpringBoot项目中使用Swagger2,及其详细介绍注解
文章目录
- SpringBoot项目中使用Swagger2,及其详细介绍注解
- 什么是swagger2
- 1、swagger2的配置
- 1.1、引入Swagger2依赖
- 1.2、编写SwaggerConfig配置文件
- 1.3、配置类及其参数说明
- 2、swagger2 注解整体说明
- 2.1、请求类的描述
- 2.2、方法和方法参数的描述
- 2.3、方法的响应状态的描述
- 2.4、对象的描述
- 3、请求类的描述
- 3.1、@[Api](=Api&spm=1001.2101.3001.7020):请求类的说明
- 3.2、示例:
- 4、方法和方法参数的描述
- 4.1、@ApiOperation:方法的说明
- 4.2、@ApiImplicitParams、@ApiImplicitParam:方法参数的说明
- 4.3、示列:
- 5、对象的描述
- 5.1、@ApiModel:对象的整体说明
- 5.2、@ApiModelProperty 对象中每个参数的说明
- 5.3、示例:
- 入参是对象,即 `@RequestBody` 时, 用于封装请求
什么是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";@Beanpublic 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("张三", "", "xxxxx@163")).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");
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省略
}
更多推荐
SpringBoot项目中使用Swagger2,及其详细介绍注解
发布评论