天天看點
傳回

【狂神說】Swagger入門Swagger

目錄

  • Swagger
    • 1、Swagger簡介
      • 1.1、Swagger
    • 2、SpringBoot內建Swagger
      • 2.1、內建
      • 2.2、拓展
    • 3、配置Swagger
      • 3.1、修改Swagger的預設資訊
      • 3.2、配置掃描接口
      • 3.3、配置Swagger開關
      • 3.4、配置API分組
      • 3.5、Swagger常用注解
    • 4、總結

Swagger

1、Swagger簡介

前後端分離時代（流行的：Vue+SpringBoot）
  • 後端：控制層、業務層、資料通路層
  • 前端：前端控制層、視圖層
    • 前端可以僞造資料，不需要後端
前後端優點
  • 前後端資料互動通過API
  • 前後端相對獨立，松耦合
  • 前後端甚至可以部署在不同的伺服器上
産生問題
  • 前後端協調，可能會存在沖突問題
解決方法
  • 制定schema計劃綱要
  • 制定word文檔計劃
  • 前後端分離
    • 前端測試後端接口
    • 後端提供接口，并進行及時更新最新消息和改動

1.1、Swagger

  • 号稱世界上最流行的API架構
  • Restful Api 文檔線上自動生成器 => API 文檔 與API 定義同步更新
  • 直接運作，線上測試API
  • 支援多種語言 （如：Java，PHP等）

2、SpringBoot內建Swagger

2.1、內建

  • 建立SpringBoot項目（并添加web依賴支援）
  • 導入相關依賴 
    <!--剛開始使用3.0.0版本不能通路jar包，然後就降了jar包版本-->
<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>
  • 編寫HelloController，測試項目搭建沒有問題
  • 要使用Swagger還需要編寫它對應的配置類 
    import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration//java配置類
@EnableSwagger2//開啟Swagger2的自動配置
public class SwaggerConfig {
}
  • 通路測試：

    http://localhost:8080/swagger-ui.html

    進入Swagger界面
    【狂神說】Swagger入門Swagger

2.2、拓展 

# 搞清楚這行代碼是幹什麼的
spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

3、配置Swagger

3.1、修改Swagger的預設資訊

  • 注入Docket的bean執行個體（Swagger的執行個體是Docket） 
    @Bean//注入Docket類型的bean來配置（自定義）Swagger的具體參數
public Docket getDocket(){
  //通過該類的apiInfo方法來修改預設的配置資訊
  return new Docket(DocumentationType.SWAGGER_2);
}
  • 修改預設的的Swagger資訊

    通過調用Docket對象的apiInfo方法）

    注意：apiInfo方法的參數類型是ApiInfo類型

    @Bean//注入Docket類型的bean來配置（自定義）Swagger的具體參數
public Docket getDocket(){
  //通過該類的apiInfo方法來修改預設的配置資訊
  return new Docket(DocumentationType.SWAGGER_2).apiInfo();
}
    【狂神說】Swagger入門Swagger
  • 修改ApiInfo類中的預設配置資訊 
    public ApiInfo apiInfo(){
  Contact contact = new Contact("mtf", "https://baidu.com", "[email protected]");

  return new ApiInfo("mtf學習Swagger",
                     "邊學邊總結",
                     "a1.0",
                     "urn:tos",
                     contact,
                     "Apache 2.0",
                     "http://www.apache.org/licenses/LICENSE-2.0",
                     new ArrayList());
}
  • 最後調用該方法，傳回的ApiInfo類執行個體指派給apiInfo方法 
    @Bean//注入Docket類型的bean來配置（自定義）Swagger的具體參數
public Docket getDocket(){
  //通過該類的apiInfo方法來修改預設的配置資訊
  return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
    【狂神說】Swagger入門Swagger

3.2、配置掃描接口

指定要掃描的接口
  • 構造Docket類執行個體時通過調用select方法配置
  • 之後通過調用

    apis()

     方法
    【狂神說】Swagger入門Swagger
    @Bean//注入Docket類型的bean來配置（自定義）Swagger的具體參數
public Docket getDocket(){
  //通過該類的apiInfo方法來修改預設的配置資訊
  return new Docket(DocumentationType.SWAGGER_2).
    apiInfo(apiInfo())
    .select()
    .apis(RequestHandlerSelectors.basePackage("com.mtf.controller"))
    .build();
}
過濾（不掃描）
  • 構造Docket類執行個體時通過調用select方法配置
  • 之後通過調用

    paths()

     方法
    【狂神說】Swagger入門Swagger
    @Bean//注入Docket類型的bean來配置（自定義）Swagger的具體參數
public Docket getDocket(){
  //通過該類的apiInfo方法來修改預設的配置資訊
  return new Docket(DocumentationType.SWAGGER_2).
    apiInfo(apiInfo())
    .select()
    .apis(RequestHandlerSelectors.basePackage("com.mtf.controller"))
    //過濾掉該路徑下的所有接口，意識就是不掃描下面路徑的所有接口
    .paths(PathSelectors.ant("../controller/**"))
    //上面設定相當于什麼也沒有掃描
    .build();
}

3.3、配置Swagger開關

  • 構造Docket類執行個體時通過調用enable方法配置
    【狂神說】Swagger入門Swagger
    @Bean//注入Docket類型的bean來配置（自定義）Swagger的具體參數
public Docket getDocket(){
  //通過該類的apiInfo方法來修改預設的配置資訊
  return new Docket(DocumentationType.SWAGGER_2).
    apiInfo(apiInfo())
    .enable(false)
    .select()
    .apis(RequestHandlerSelectors.basePackage("com.mtf.controller"))
    //過濾掉該路徑下的所有接口，意識就是不掃描下面路徑的所有接口
    //.paths(PathSelectors.ant("../controller/**"))
    .build();
}
思考：在開發環境中開啟Swagger，在釋出環境中關閉Swagger
  • 首先：需要判斷環境
  • 其次：開啟和關閉Swagger 
@Bean//注入Docket類型的bean來配置（自定義）Swagger的具體參數
public Docket getDocket(Environment environment){
  //設定要使用Swagger的環境
  Profiles profiles = Profiles.of("pro");
  //判斷目前是否處于該環鏡
  boolean b = environment.acceptsProfiles(profiles);

  //通過該類的apiInfo方法來修改預設的配置資訊
  return new Docket(DocumentationType.SWAGGER_2).
    apiInfo(apiInfo())
    .enable(b)
    .select()
    .apis(RequestHandlerSelectors.basePackage("com.mtf.controller"))
    //過濾掉該路徑下的所有接口，意識就是不掃描下面路徑的所有接口
    //.paths(PathSelectors.ant("../controller/**"))
    .build();
}

3.4、配置API分組

配置多個分組
  • 構造Docket類執行個體時通過調用groupName方法配置 
@Bean
public Docket docket1(){
  return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}

@Bean
public Docket docket2(){
  return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}

@Bean
public Docket docket3(){
  return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}
【狂神說】Swagger入門Swagger
實體類配置
  • 建立User實體類 
    package com.mtf.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
//@Api等價
@ApiModel("使用者實體類")
public class User {
  @ApiModelProperty("使用者id")
  //注意這裡的屬性修飾符，如果用的修飾符是“private”，那麼頁面中的屬性和屬性注釋不會顯示
  public Integer id;
  @ApiModelProperty("使用者昵稱")
  public String name;
}
  • 編寫控制類 
    package com.mtf.controller;

import com.mtf.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
@Api(tags = "Hello控制類")
@RestController
public class HelloController {
    @ApiOperation("你好Swagger")
    @GetMapping("/swagger")
    public String hello(){
        return "hello,swagger!";
    }
    @ApiOperation("獲得使用者")
    @PostMapping("/user")
    public User user(){
        return new User();
    }
    @ApiOperation("測試")
    @PostMapping("/test")
    public String test(){
        return "test";
    }
}
    【狂神說】Swagger入門Swagger

3.5、Swagger常用注解

Swagger注解 說明
@Api(tags = “xxx子產品說明”) 作用在子產品類上
@ApiOperation(“xxx接口說明”) 作用在接口方法上
@ApiModel(“xxxPOJO說明”) 一般作用在實體類上
@ApiModelProperty(value = “xxx屬性說明”,hidden = true) 作用在類方法和屬性上，hidden設定為true可以隐藏該屬性
@ApiParam(“xxx參數說明”) 作用在參數、方法和字段上，類似@ApiModelProperty

4、總結

  • 通過Swagger可以添加一些難了解的類、屬性的注釋資訊
  • 接口文檔實時更新
  • 線上測試
  • 注意：在正式釋出是關閉Swagger（出于安全考慮）
swagger java spring boot spring
上一篇: Struts2之2.5.10配置
下一篇: 23.9 Application exit application 退出

繼續閱讀