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: 用在属性上,描述响应类的属性