SpringBoot RESTful接口

1.常用注解开发RESTful接口

@RestController
1. 将注解的类注入到Spring的环境
2. 相当于@Controller + @ResponseBody
3. JSON格式的数据响应
@RequestMapping
1. 类上的注解表示注解的Controller类的路径
@PathVariable
1. 路径上的变量
@PathVariable & RequestParam
1. @PathVariable用于接收URL上的{参数}
2. @RequestParam用于接收普通方式提供的参数
@RequestBody & @RequestParam
1. JSON数据建议用@RequestBody,会分配实体类中的所有属性
2. @RequestParam适合接收单个的参数
3. @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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


				<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


// config/Swagger2.java
package com.haven.config;

import org.springframework.beans.factory.annotation.Configurable;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.w3c.dom.DocumentType;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author HavenTong
 * @date 2019/10/29 3:26 下午
 */
@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.haven"))
                .paths(PathSelectors.regex("/rest/.*"))
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restfun风格")
                .termsOfServiceUrl("http://www.zimug.com")
                .version("1.0")
                .build();
    }
}

之后启动项目，通过http://localhost:8080/swagger-ui.html即可访问swagger-ui

可以在方法上添加更详细的注解：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


    @ApiOperation(value = "添加文章", notes = "添加新的文章", tags = "Article", httpMethod = "POST")
//    @ApiImplicitParams({
//            @ApiImplicitParam(name = "title", value = "文章标题", required = true, dataType = "String"),
//            @ApiImplicitParam(name = "content", value = "文章内容", required = true, dataType = "String"),
//            @ApiImplicitParam(name = "author", value = "文章作者", required = true, dataType = "String")
//    })
    @ApiResponses({
            @ApiResponse(code = 200, message = "成功", response = AjaxResponse.class),
            @ApiResponse(code = 400, message = "用户输入错误", response = AjaxResponse.class),
            @ApiResponse(code = 500, message = "系统内部错误", response = AjaxResponse.class)
    })
    @RequestMapping(value = "/article", method = RequestMethod.POST, produces = "application/json")
    public AjaxResponse saveArticle(@RequestBody Article article){

由于采用@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: 用在属性上，描述响应类的属性

SpringBoot RESTful接口#

1.常用注解开发RESTful接口#

2.JSON数据处理和Postman测试#

(1) 常用注解#

(2) 序列化与反序列化#

3. Postman使用#

4. 使用Swagger 2发布API文档#

整合Swagger 2#

Swagger 2常用注解#