Swagger

接口介绍

1.1 接口概念

狭义的理解：就是控制器中可以接受用户请求的某个方法

应用程序编程接口，简称API（Application Programming Interface），就是软件系统不同组成部分衔接的约定

1.2 接口规范

作为一个后端开发者，我们不仅要完成接口程序的开发，还要编写接口的说明文档——接口规范

2 Swagger

前后端分离开发，后端需要编写接口说明文档，会耗费比较多的时间

swagger是一个用于生成服务器接口的规范性文档、并且能够对接口进行测试的工具

2.1 作用

• 生成接口说明文档
• 对接口进行测试

2.2 Swagger整合

• 在api子工程添加依赖（Swagger2 \ Swagger UI）

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

• 在api子工程创建swagger的配置（Java配置方式）

  @Configuration
  @EnableSwagger2
  public class SwaggerConfig {
  
      /*swagger会帮助我们生成接口文档
      * 1：配置生成的文档信息
      * 2: 配置生成规则*/
  
      /*Docket封装接口文档信息*/
      @Bean
      public Docket getDocket(){
  
          //创建封面信息对象
          ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
          apiInfoBuilder.title("《锋迷商城》后端接口说明")
                  .description("此文档详细说明了锋迷商城项目后端接口规范....")
                  .version("v 2.0.1")
                  .contact( new Contact("亮哥","www.liangge.com","liangge@wang.com") );
          ApiInfo apiInfo =  apiInfoBuilder.build();
  
          Docket docket = new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(apiInfo) //指定生成的文档中的封面信息：文档标题、版本、作者
                  .select()
                  .apis(RequestHandlerSelectors.basePackage("com.qfedu.fmmall.controller"))
                  .paths(PathSelectors.any())
                  .build();
  
          return docket;
      }
  
  }
  

• 测试：

  • 启动SpringBoot应用，访问：http://localhost:8080/swagger-ui.html

2.3 Swagger注解说明

swagger提供了一套注解，可以对每个接口进行详细说明

@Api 类注解，在控制器类添加此注解，可以对控制器类进行功能说明

@Api(value = "提供商品添加、修改、删除及查询的相关接口",tags = "商品管理")

@ApiOperation方法注解：说明接口方法的作用

@ApiImplicitParams和@ApiImplicitParam 方法注解，说名接口方法的参数

@ApiOperation("用户登录接口")
@ApiImplicitParams({
    @ApiImplicitParam(dataType = "string",name = "username", value = "用户登录账号",required = true),
    @ApiImplicitParam(dataType = "string",name = "password", value = "用户登录密码",required = false,defaultValue = "111111")
})
@RequestMapping(value = "/login",method = RequestMethod.GET)
public ResultVO login(@RequestParam("username") String name,
                      @RequestParam(value = "password",defaultValue = "111111") String pwd){
    return userService.checkLogin(name,pwd);
}

@ApiModel和@ApiModelProperty 当接口参数和返回值为对象类型时，在实体类中添加注解说明

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "User对象",description = "用户/买家信息")
public class User {

    @ApiModelProperty(dataType = "int",required = false)
    private int userId;

    @ApiModelProperty(dataType = "String",required = true, value = "用户注册账号")
    private String userName;

    @ApiModelProperty(dataType = "String",required = true, value = "用户注册密码")
    private String userPwd;

    @ApiModelProperty(dataType = "String",required = true, value = "用户真实姓名")
    private String userRealname;

    @ApiModelProperty(dataType = "String",required = true, value = "用户头像url")
    private String userImg;
}

@ApiIgnore接口方法注解，添加此注解的方法将不会生成到接口文档中

2.4 Swagger-ui 插件

• 导入插件的依赖

  <dependency>
      <groupId>com.github.xiaoymin</groupId>
      <artifactId>swagger-bootstrap-ui</artifactId>
      <version>1.9.6</version>
  </dependency>
  

• 文档访问

  http://ip:port/doc.html

3 RESTful

前后端分离开发的项目中，前后端之间是接口进行请求和响应，后端向前端提供请求时就要对外暴露一个URL；URL的设计不能是随意的，需要遵从一定的设计规范——RESTful

RESTful 是一种Web api的标准，也就是一种url设计风格/规范

• 每个URL请求路径代表服务器上的唯一资源

  传统的URL设计：
  	http://localhost:8080/goods/delete?goodsId=1    商品1
      http://localhost:8080/goods/delete?goodsId=2    商品2
  
  RESTful设计：
  	http://localhost:8080/goods/delete/1    商品1
  	http://localhost:8080/goods/delete/2    商品2
  

  @RequestMapping("/delete/{gid}")
  public ResultVO deleteGoods(@PathVariable("gid") int goodsId){
      System.out.println("-----"+goodsId);
      return new ResultVO(10000,"delete success",null);
  }
  

• 使用不同的请求方式表示不同的操作

  SpringMVC对RESTful风格提供了很好的支持，在我们定义一个接口的URL时，可以通过@RequestMapping(value="/{id}",method=RequestMethod.GET)形式指定请求方式，也可使用特定请求方式的注解设定URL

  @PostMapping("/add")

  @DeleteMapping("/{id}")

  @PutMapping("/{id}")

  @GetMapping("/{id}")

  • post 添加
  • get 查询
  • put 修改
  • delete 删除
  • option (预检)

  根据ID删除一个商品：
  //http://localhost:8080/goods/1   [delete]
  @RequestMapping(value = "/{id}",method = RequestMethod.DELETE)
  public ResultVO deleteGoods(@PathVariable("id") int goodsId){
      System.out.println("-----"+goodsId);
      return new ResultVO(10000,"delete success",null);
  }
  
  根据ID查询一个商品：
  //http://localhost:8080/goods/1    [get]
  @RequestMapping(value = "/{id}",method = RequestMethod.GET)
  public ResultVO getGoods(@PathVariable("id") int goodsId){
          return null;
  }
  

• 接口响应的资源的表现形式采用JSON（或者XML）

• 在控制类或者每个接口方法添加@ResponseBody注解将返回的对象格式为json

• 或者直接在控制器类使用@RestController注解声明控制器

• `前端(Android\ios\pc)通过无状态的HTTP协议与后端接口进行交互

swagger2 3.0.0版本

1.springboot项目检查Maven中所导入的依赖

3.0.0版本：需添加……springboot-starter

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
</dependency>

3.0.0版本以下：

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

2.配置Config

3.0.0之前版本需使用@EnableSwagger2注解
3.0.0版本则不需要@EnableSwagger2注解，取而代之是@EnableOpenApi

3.swagger-ui界面url地址的改变

3.0.0之前的版本访问是：
/swagger-ui.html
3.0.0版本访问是：
/swagger-ui/index.html