Swagger2--自動生成接口文檔工具學習

文章目錄

• Swagger2 學習
• 1、前提準備
• 2、快速體驗
• 3、Swagger 配置
• • （1）設定基本資訊
  • （2）設定接口文檔的相關配置
  • • • apis方法
      • paths方法
      • build 方法
      • 1）設定掃描包路徑
      • 2）自定義注解進行使用
      • 3）路由範圍決定
      • 4）配置生效
  • （3）配置小結
• 4、Swagger 常用注解
• • （1）@Api
  • （2）@ApiOperation
  • （3）@ApiParam
  • （4）@ApiImplicitParam、@ApiImplicitParams
  • （5）@ApiIgnore
  • （6）@ApiModel+@APiProperty

Swagger2 學習

1、前提準備

   在swagger2版本中，需要使用swagger2，并可以從浏覽器中ui渲染，必須導入兩個依賴 （這裡放的是使用人數最多的依賴版本）

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

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>           

複制

經過swagger注解之後，會将接口中的資料渲染到浏覽器中，檢視接口文檔的位址是

localhost:8080/swagger-ui.html           

複制

在開發的時候前後端分離需要生成接口文檔，我們需要在 啟動類 或者 配置類 上打開*Swagger服務,需要使用@EnableSwagger2 注解

package com.study;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}           

複制

2、快速體驗

  寫一下控制層的接口, swagger 會預設根據@Conrtoller注解識别 Controller層裡的接口，直接渲染到接口文檔的ui界面中

package com.study.controller;

import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    @GetMapping("/get")
    public String get(String username,String password){
        return "get";
    }

    @PostMapping("/post")
    public String post(int a,int b){
        return "post";
    }
}           

複制

啟動項目，輸入swagger-ui的位址

localhost:8080/swagger-ui.html           

複制

因為很多都沒有進行配置，是以很多部分顯示的都是預設資訊，

我們寫的控制層接口已經識别到了，UserController。

點開具體的接口，檢視接口文檔的具體資訊

3、Swagger 配置

（1）設定基本資訊

Docket :描述一組文檔的所有資訊，相當于Swagger文檔全局的上下文對象，可以建立多個docket實作文檔分組檢視不同人員寫的接口

/**
     * 建立以Docket類型的對象，并使用Spring容器進行管理
     * Docket是Swagger中的全局配置對象
     * @return
     */

    @Bean
    public Docket docket(){
       	Docket docket = new Docket(DocumentationType.SWAGGER_2); 
        // 指定Swagger文檔的版本
       	return docket;
    }           

複制

ApiInfo ：是生成文檔ui上面的一些作者、網址url、文檔描述、文檔版本号等資訊，這些需要我們手動去設定，這個對象是通過建構器 ApiInfoBuilder 得到的

手動設定文檔相關資訊

ApiInfoBuilder builder = new ApiInfoBuilder();

        builder.title("文檔的标題"); // 文檔的标題
        builder.description("這是文檔的一些描述，描述描述描述描述描述描述描述描述描述描述"); // 文檔的描述
        builder.contact(new Contact("文檔名字","相關的網站位址","相關的郵箱"));// 文檔名字--對應的連接配接--發送的郵箱位址
        builder.version("2,0");// 版本号
        builder.license("文檔相關的許可證"); // 許可證名字
        builder.licenseUrl("文檔相關的許可證位址");// 許可證對應的網站位址

        ApiInfo apiInfo = builder.build();
        docket.apiInfo(apiInfo);           

複制

運作項目，檢視效果

（2）設定接口文檔的相關配置

  主要通過 ApiSelectBuilder 提供的方法來進行設定接口的一些配置，ApiSelectBuilder 通過 docket.select() 方法拿到，最後需要使用build方法 在覆寫docket對象即可完成設定。如同下面的方式

docket = dokcet.select().method1().method2.build();           

複制

介紹方法

apis方法

實作設定包掃描路徑、設定注解使用規則等功能

參數 Predicate 這個是規則選擇器，我們會使用一些子類作為參數使用

RequestHandlerSelectors 這個類型是選擇處理器，也提供很多靜态方法供我們使用，進行接口設定。

PathSelectors 這個是路徑選擇器，可通過他提供的regex方法，使用正規表達式選擇路由建立文檔

Predicates，規則相關的類提供的很多靜态方法，取反、非空等

paths方法

設定符合路由文檔建立，其中使用表達式

build 方法

将build的對象重新賦給docket

1）設定掃描包路徑

swagger預設是掃描啟動類所在的包以及所有子包的路徑，我們可以手動的進行指定

通過apis方法中的參數 RequestHandlerSelectors 提供的類方法可以實作掃描

// select() 傳回的是APISelectBuilder,提供很多方法
        ApiSelectorBuilder selectorBuilder = docket.select();
        selectorBuilder.apis(RequestHandlerSelectors.basePackage("com.study.controller"));           

複制

2）自定義注解進行使用

這個就不講了，一般用不着

3）路由範圍決定

決定某些路由下的接口可以建立文檔，路由之外的路由不可以建立文檔，使用paths方法

selectorBuilder.paths(PathSelectors.regex("/swagger/.*"));// 使用正規表達式，限制生成API文檔的路由位址
         // 上面正規表達式的意思是 以 swagger開頭的後面比對任意多個字元的路由           

複制

4）配置生效

使用build方法，再将配置好的docket對象賦給先前建立的docket

docket = selectBuilder.build();           

複制

（3）配置小結

通過配置docket我們做了一下事情

• 設定文檔的基本資訊（題目、描述…）
• 完成接口的一些建立規則（掃描具體路徑、自動義注解、路由範圍決定）
• 将之前設定的所有資訊傳回給docket，最終由spring托管生效

下面我們放一下swagger配置的完整的代碼

package com.study.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 建立以Docket類型的對象，并使用Spring容器進行管理
     * Docket是Swagger中的全局配置對象
     * @return
     */

    @Bean
    public Docket docket(){

        Docket docket = new Docket(DocumentationType.SWAGGER_2); // 指定Swagger文檔的版本

        ApiInfo apiInfo =new ApiInfoBuilder().title("Swagger2 學習文檔")
                                             .contact(new Contact("Swagger名字小字","https://www.baidu.com","[email protected]"))
                                             .description("這是文檔的描述資訊")
                                             .version("2.9")
                                             .license("許可證資訊")
                                             .licenseUrl("https://www.baidu.com")
                                             .build();
        docket.apiInfo(apiInfo);

        // 由select() 生成selectBuilder,放入建立文檔的規則等，在通過 build 返還給docket，使配置生效
        docket = docket.select().apis(RequestHandlerSelectors.basePackage("com.study.controller")) // 設定掃描包路徑
                                .paths(PathSelectors.regex("/swagger/.*"))  // 使用正規表達式，限制生成API文檔的路由位址
                                .build();
        
        docket = docket.groupName("RAIN7");// 設定目前這一組文檔的 空間名，或者設定docket的名字，因為可以有多個docket對應小組中不同人的接口

           return docket;
    }
}           

複制

controller層的接口，設定 “/swagger” 路由

package com.study.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/swagger")
public class UserController {

    @GetMapping("/get")
    public String get(String username,String password){
        return "get";
    }

    @PostMapping("/post")
    public String post(int a,int b){
        return "post";
    }
}           

複制

運作項目，檢視結果

4、Swagger 常用注解

（1）@Api

@Api 是類上的注解，控制整個類生成接口資訊的内容

• value:類的名稱，菜單的标簽，隻能當一個值
• tags：菜單的标簽，可以有多個值，可以生成多個ui上的接口菜單，也就是目前接口的多個副本
• description：類接口的描述，已經過時

什麼是接口菜單？

@RestController
@RequestMapping("/swagger")
@Api(tags = {"User控制器","User資訊增删改查"},description = "這是目前控制器的描述")
public class UserController {

    @GetMapping("/get")
    public String get(String username,String password){
        return "get";
    }

    @PostMapping("/post")
    public String post(int a,int b){
        return "post";
    }
}           

複制

運作項目，檢視ui效果

  通常我們就是在類上使用 預設的value就可以了，在菜單的說明在這個菜單下的接口都是什麼類型的，分個類說明一下就可以了。

（2）@ApiOperation

方法注解，可以給類型定義，也可以給方法定義

• value：給目前方法的一個描述
• notes: 方法的标記資訊
• tags：方法的多個副本，不太用，字元串數組

在方法上加上注解，标記方法描述 value、方法筆記 notes

@GetMapping("/get")
    @ApiOperation(value = "get方法的描述",notes = "get方法的筆記")
    public String get(String username,String password){
        return "get";
    }           

複制

檢視效果接口的ui效果

（3）@ApiParam

描述屬性（參數），還可以描述方法，這個注解并不是經常使用，經常使用@ApiImplicitParam作為代替

• name 參數名稱
• value 參數的描述
• required 參數是否是必要的，預設為假
• example 參數舉例，字元串類型，隻能給非body類型的參數提供簡單例子
• readOnly 預設為false

如果加上@ApiParam，預設參數使用@RequestBody進行接收才能接收到，預設放到了請求的body中

參數也加上 api注解

@GetMapping("/get")
    @ApiOperation(value = "get方法的描述",notes = "get方法的筆記")
    public String get(@ApiParam(name = "使用者名(username)",value = "新增使用者需要提供使用者名",required = true) String username,
                      @ApiParam(name = "密碼(password)",value = "新增使用者需要提供密碼",required = true) String password){
        return "get";
    }           

複制

檢視ui效果

（4）@ApiImplicitParam、@ApiImplicitParams

  放在方法上面,效果和@ApiParam一樣，但是 這個注解範圍更廣,描述唯一的方法參數，我們經常使用這個參數作為方法參數的解釋，因為在方法參數前面還得跟springmvc的注解表示參數的接受類型，代碼過于備援了

• name 參數名稱
• value 參數描述
• parameterType 代表參數應該放在請求的什麼地方
  • header–>放在請求頭。請求參數的擷取：@RequestHeader(代碼中接收注解）
  • query -->用于get請求的參數拼接。請求參數的擷取：@RequestParam(代碼中接收注解)
  • path -->（用于restful接口）–>請求參數的擷取：@PathVariable(代碼中接收注解)
  • body -->放在請求體。請求參數的擷取：@RequestBody(代碼中接收注解)
• required 是否有必要
• dataType 參數的類型

@ApiImplicitParams,他就是@ApiImplicitParam的集合，以數組的方式，放入注解中

@PostMapping("/post/{m}/{n}")
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "m",value = "m參數的描述",dataType = "int",paramType = "path",example = "1"),
            @ApiImplicitParam(name = "n",value = "n參數的描述",dataType = "int",paramType = "path",example = "1")
    })
    public String  post(@PathVariable("m") int m, @PathVariable("n") int n){
        return String.format("%d+%d=%d",m,n,m+n);
    }           

複制

ui效果

（5）@ApiIgnore

放在方法上，意思是忽略這個接口，不生成文檔

（6）@ApiModel+@APiProperty

  通過注解描述實體類型，為什麼要描述實體？因為有時候接口傳回的是一個實體對象，是以會生成關于傳回對象的解釋文檔

@ApiModel放在實體類上

• value 實體類的名字
• description 實體類的描述

@ApiProperty放在屬性上

• name 屬性的名字
• value 屬性的描述
• example 屬性填入的值的例子
• required 屬性是否必填

寫一個User實體類，進行解釋說明

package com.study.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

import java.io.Serializable;

@ApiModel(value = "User類的名字",description = "User類的描述")
public class User implements Serializable {
    @ApiModelProperty(name = "username的名字",value = "username的描述",required = true,example = "admin",hidden = false)
    public String username;

    @ApiModelProperty(name = "password的名字",value = "password的描述",required = true,example = "admin",hidden = false)
    public String password;

    public String getUsername() {
        return username;
    }

    public User(String username, String password) {
        this.username = username;
        this.password = password;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}           

複制

在controller層寫一個接口傳回User類型的響應

@ApiOperation("get方法")
    @PutMapping("/getUser")
    public User getUser(){
        User user = new User("admin","admin");
        return user;
    }           

複制

  當我們在控制層的代碼有傳回值類型是 User對象的話，那麼在接口文檔的最下面就會有 Models的解釋說明

記錄就寫到這裡，希望大家多多練習!