一、Swagger是什么
说得直白点,Swagger就是一款RESTFUL接口文档工具,后端开发人员可用它模拟前端请求,调试程序,前端人员可用它作为接口文档,与后端开发进行交互
二、Swagger配置
本文搭建一个简单的Springboot项目,演示如何在Springboot中集成Swagger
- 创建Springboot项目
1.创建项目较简单,此处采用idea自带的Spring Initializr
创建项目
- 引入springboot依赖和Swagger依赖
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.1.6.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.study.swagger</groupId>
<artifactId>test-swagger</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>test-swagger</name>
<description>Demo project for Spring Boot</description>
<properties>
<java.version>1.8</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<!--引入swagger依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
</dependencies>
- 配置Swagger
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//此处 basePackage表示项目要使用swagger包路径
.apis(RequestHandlerSelectors.basePackage("com.study.swagger.testswagger"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("配置swagger")
.description("演示swagger如何配置")
.version("0.0.1")
.build();
}
}
- 启动类开起EnableSwagger注解
@SpringBootApplication
@EnableSwagger2 //开启swagger注解
public class TestSwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(TestSwaggerApplication.class, args);
}
}
- 创建controller层,此处只为模拟
@RestController
@RequestMapping("/test")
public class TestSwagger {
@PostMapping(value = "/add")
public String addUser(@RequestBody
@ApiParam(name = "用户", value = "传入json格式", required = true)
User user) {
return "新增用户:" + user.getUserName();
}
@PutMapping(value = "/update")
public String updateUser(@RequestBody
@ApiParam(name = "用户", value = "传入json格式", required = true)
User user) {
return "更新用户:" + user.getUserName();
}
}
- 登录swagger ui查看
http://localhost:8081/swagger-ui.html
1.8081:为配置端口
2.显示如下图,则配置swagger配置成功
三、Swagger注解
1.用于类@Api
-
常用属性说明
value:表示描述信息,当使用tag时,设置的value值将会被覆盖
tags:表示描述信息
-
用法
由于value值会被tags覆盖,常用tags值即可
@RestController @RequestMapping("/test"明) @Api(tags = "测试swagger") public class TestSwagger { }
2.用于方法
1.@ApiOperation:用于方法整体说明
-
常用属性说明
- value:描述方法用途
- notes:对方法进行备注说明
- tags:可以将同一个类中方法进行分类展示
- hidden:隐藏方法
-
用法
@PutMapping(value = "/update/user") @ApiOperation(value = "更新用户",tags = "用户相关",notes="删除用户",hidden = true) public String updateUser(){ } @PutMapping(value = "/add/order") @ApiOperation(value = "删除用户",tags = "商品相关",notes="增加用户notes") public String addOrder(){ }
[外链图片转存失败(img-ZNhac9oH-1564650792741)(/home/zycao/.config/Typora/typora-user-images/1564627909789.png)]
2.@ApiImplicitParam && @ApiImplicitParams
用于方法参数设置,主要用于get请求参数配置
@@ApiImplicitParam:表示单个属性
@@ApiImplicitParams:表示多个属性
-
常用属性说明
- name:设置属性名
- value:属性描述
- defaultValue:默认值
- required:是否必填,默认false
- dataType:表示字段类型,默认String
- paramType:表示请求参数格式
- body:表示实体
- path:表示参数在路径上
/getUser/api/{id}
- query:表示get请求参数
-
用法
@GetMapping("/getUser/{id}") @ApiImplicitParams({ @ApiImplicitParam(name = "user_name",value="用户名",required=true), @ApiImplicitParam(name = "id") }) public String getUserByNameAndId(@RequestParam(name="user_name")String userName, Integer id) { return userName+":"+id; }
3.用于属性
@ApiParam():表示接收get请求参数,但实验所得默认为paramType:"body"
,而且不能修改,使用@ApiParam()通常与 @RequestParam()配置合使
@ApiModel():主要用于接收对象,用于post请求接收的参数,通常与@RequestBody()配置使用
@ApiModelProperty():主要用于接收对象属性上
-
@ApiParam用法
@GetMapping("/getUser/{id}") public String getUserByNameAndId( @ApiParam(value = "用户名", required = true) @RequestParam(name="user_name") String userName, @PathVariable(value = "id") Integer id) { return userName + ":" + id; }
-
@ApiModel && @ApiModelProperty()
@ApiModel:通常与@RequestBody配合使用,表示接收实体
@ApiModelProperty:通常与JsonProperty配置使用,可以定义前端传入字段格式为指定格式,通常用于前端格式为
下划线
到后端驼峰
@Data @ApiModel public class User { /**年龄*/ @ApiModelProperty(value = "用户年龄") @JsonProperty("age") private Integer age; /**用户id*/ @ApiModelProperty(name="user_id",value = "用户id") @JsonProperty("user_id") private Integer id; /**用户名*/ @ApiModelProperty(value = "用户名") @JsonProperty("user_name") private String userName; }
4.Swagger使用
Swagger只是接口文档,它的注解验证只针对Swagger页面请求效,如果要保证通过rest请求后端也能起到验证作用,则需要配合javax.validation.constraints
验证使用,现就几种常用业务场景进行介绍
-
通用设置
@Api(tags="设置对象说明信息") @RestController public Class UserController(){ @ApiOperation(value="设置方法说明信息",tags="设置方法分类展示",notes="设置方法备注信息") public String addUser(){ } }
-
GET请求
通过@ApiImplicitParams配置swagger的参数列表
通过@RequestParam:配置rest请求参数
@ApiOperation(value = "获取用户", tags = "用户相关", notes = "增加用户notes") @GetMapping(value = "/user/list") @ApiImplicitParams({ @ApiImplicitParam(name = "user_name", value = "用户名",required=true), @ApiImplicitParam(name = "user_id", value = "用户id",required=true) }) public String listUser( @RequestParam(name="user_id") Integer userId, @RequestParam(name="user_name") String userName) { return "查询用户id= " + userId + " 的用户"+userName; }
-
POST请求
@ApiModel:配置swagger
@ApiModelproperty:配置字段说明信息,required配置默认必填
@JsonProperty:配置序列化字段样式
@NotNull:配置数字不能为空
@NotEmpty:配置字符串不能为空
@Min:表示最小值
要让验证生效,必须增加@Validated注解
@ApiOperation(value = "增加用户", tags = "用户相关", notes = "增加用户notes") @PostMapping(value = "/add/user") public String addUser(@RequestBody @Validated User user) { return "新增用户:" + user.getUserName(); } @Data @ApiModel public class User { /**年龄*/ @ApiModelProperty(value = "用户年龄",required = true) @JsonProperty("age") private Integer age; /**用户id*/ @ApiModelProperty(name="user_id",value = "用户id",required = true) @JsonProperty("user_id") @NotNull @Min(value = 1) private Integer id; /**用户名*/ @ApiModelProperty(value = "用户名",required = true) @JsonProperty("user_name") @NotEmpty private String userName; }