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 = "")：配置时间格式

  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

<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>

// 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

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

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

  ​

  ​