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","[email protected]") );
          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