SpringBoot RESTful接口
1.常用注解开发RESTful接口
-
@RestController
- 将注解的类注入到Spring的环境
- 相当于
@Controller
+@ResponseBody
- JSON格式的数据响应
-
@RequestMapping
- 类上的注解表示注解的Controller类的路径
-
@PathVariable
- 路径上的变量
-
@PathVariable
&RequestParam
@PathVariable
用于接收URL上的{参数}@RequestParam
用于接收普通方式提供的参数
-
@RequestBody
&@RequestParam
-
JSON数据建议用
@RequestBody
,会分配实体类中的所有属性 -
@RequestParam
适合接收单个的参数 -
@RequestBody
可以接收嵌套的数据结构
-
2.JSON数据处理和Postman测试
Spring Boot默认使用Jackson
(1) 常用注解
-
@JsonIgnore
:加在属性上表示在序列化和反序列化的过程中将它忽略 -
@JsonProperty
:为属性起别名 -
@JsonPropertyOrder
:加在类上 -
@JsonInclude(JsonInclude.Include.NON_NULL)
: 当属性不为空的时候,进行序列化;否则不进行 -
@JsonFormat(pattern = "", timezone = "")
:配置时间格式1 2 3 4
spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT+8
(2) 序列化与反序列化
把对象转成可传输、可存储的格式(json, xml, 二进制,甚至自定义的格式)叫序列化,反序列化为逆过程
3. Postman使用
4. 使用Swagger 2发布API文档
- 代码变,文档变,只需要少量的注解,使用Swagger就可以根据代码自动生成API文档,很好地保持了文档的及时性
- 跨语言性,支持40多种语言
- Swagge UI呈现出一份可交互式的API文档,我们可以直接在文档页面尝试API的调用,省去了准备复杂的
调用参数的过程
- 还可以将文档规范导入相关的工具(e.x. SoapUI),这些工具会为我们创建自动化的测试
整合Swagger 2
pom.xml
|
|
|
|
之后启动项目,通过http://localhost:8080/swagger-ui.html
即可访问swagger-ui
可以在方法上添加更详细的注解:
|
|
- 由于采用
@RequestBody
去接收参数,这里就不需要使用@ApiImplicitParam
注解,@ApiImplicitParam
注解与@RequestParam
注解是一一对应的。 - 建议有Swagger 2的情况下,减少与此对应的代码注释或不写
Swagger 2常用注解
-
@Api
:用在请求的类上,表示对类的说明
tags=
“说明该类的作用,可以在UI界面上看到的注解”
value=
“该参数没有什么意义,在UI界面上也能看到,所以不需要配置” -
@ApiOperation
: 用在请求的方法上,说明方法的用途、作用
value=
“说明方法的用途,作用”
notes=
“方法的备注说明” -
@ApiImplicitParams
: 用在请求的方法上,表示一组参数说明
@ApiImplicitParam
: 用在@ApiImplicitParams
注解中,指定一个请求参数的各个方面
name=
“参数名”
value=
“参数的汉字说明,解释”
required=
“参数是否必须要传”
paramType=
“参数放在哪个地方” -
header
–> 请求参数的获取:@RequestHeader
-
query
–> 请求参数的获取:@RequestParam
-
path
(用于restful接口) –> 请求参数的获取:@PathVariable
-
body
,form
不常用
dataType=
“参数类型”,默认String, 其他值dataType="Integer"
defaultValue=
“参数的默认值” -
@ApiResponses
: 用在请求的方法上,表示一组响应
@ApiResponse
: 用在@ApiResponses
中,一般用于表达一个错误的响应信息
code=
数字,e.x. 400
message=
信息,例如"请求参数没填好"
response=
抛出异常的类 -
@ApiModel
: 用于响应类上,表示一个返回响应数据的信息。(这种一般用在post创建的时候, 使用@RequestBody
的场景,请求参数无法使用@ApiImplicitParam
注解进行描述的时候)
@ApiModelProperty
: 用在属性上,描述响应类的属性