Swagger學習筆記

前言：

　　接口文檔對於前后端開發人員都十分重要。尤其近幾年流行前后端分離后接口文檔又變成重中之重。接口文檔固然重要，但是由於項 目周期等原因后端人員經常出現無法及時更新，導致前端人員抱怨接 口文檔和實際情況不一致。

　　很多人員會抱怨別人寫的接口文檔不規范，不及時更新。當時當 自己寫的時候確實最煩去寫接口文檔。這種痛苦只有親身經歷才會牢 記於心。

　　如果接口文檔可以實時動態生成就不會出現上面問題。

　　Swagger 可以完美的解決上面的問題。

Open API：

　　Open API 規范(OpenAPI Specification)以前叫做 Swagger 規范，是REST API 的 API 描述格式。

　　Open API 文件允許描述整個 API，包括：

　　　　· 每個訪問地址的類型。POST 或 GET。

　　　　·每個操作的參數。包括輸入輸出參數。

　　　　·認證方法。

　　　　·連接信息，聲明，使用團隊和其他信息。

　　Open API 規范可以使用 YAML 或 JSON 格式進行編寫。這樣更利於我們和機器進行閱讀。

　　OpenAPI 規范（OAS）為 RESTful API 定義了一個與語言無關的標 准接口，允許人和計算機發現和理解服務的功能，而無需訪問源代碼， 文檔或通過網絡流量檢查。正確定義后，消費者可以使用最少量的實 現邏輯來理解遠程服務並與之交互。然后，文檔生成工具可以使用 OpenAPI 定義來顯示 API，使用各 種編程語言生成服務器和客戶端的代碼生成工具，測試工具以及許多 其他用例。

Swagger 簡介：

　　Swagger 是一套圍繞 Open API 規范構建的開源工具，可以幫助設 計，構建，記錄和使用 REST API。

　　Swagger 工具包括的組件：

　　　　Swagger Editor  ：基於瀏覽器編輯器，可以在里面編寫 Open API規范。類似 Markdown 具有實時預覽描述文件的功能。

　　　　Swagger UI：將 Open API 規范呈現為交互式 API 文檔。用可視化UI 展示描述文件。

　　　　Swagger Codegen：將 OpenAPI 規范生成為服務器存根和客戶端 庫。通過 Swagger Codegen 可以將描述文件生成 html 格式和 cwiki 形 式的接口文檔，同時也可以生成多種言語的客戶端和服務端代碼。

　　　　Swagger Inspector：和 Swagger UI 有點類似，但是可以返回更多 信息，也會保存請求的實際參數數據。

　　　　Swagger Hub：集成了上面所有項目的各個功能，你可以以項目 和版本為單位，將你的描述文件上傳到 Swagger Hub 中。在 Swagger Hub 中可以完成上面項目的所有工作，需要注冊賬號，分免費版和收費版。

　　　　使用 Swagger，就是把相關的信息存儲在它定義的描述文件里面（yml 或 json 格式），再通過維護這個描述文件可以去更新接口文檔， 以及生成各端代碼。

一、Springfox

　　使用 Swagger 時 如 果 碰 見 版 本 更 新或 迭 代 時 ， 只 需 要 更 改 Swagger 的描述文件即可。但是在頻繁的更新項目版本時很多開發人 員認為即使修改描述文件（yml 或 json）也是一定的工作負擔，久而 久之就直接修改代碼，而不去修改描述文件了，這樣基於描述文件生 成接口文檔也失去了意義。

　　Marty Pitt 編寫了一個基於 Spring 的組件 swagger-springmvc。 Spring-fox 就是根據這個組件發展而來的全新項目。

　　Spring-fox 是根據代碼生成接口文檔，所以正常的進行更新項目版本，修改代碼即可，而不需要跟隨修改描述文件。

　　Spring-fox 利用自身 AOP 特性，把 Swagger 集成進來，底層還是Swagger。但是使用起來確方便很多。 所以在實際開發中，都是直接使用 spring-fox。

springfox快速使用：

1、編寫一個SpringBoot項目，勾選web下的spring web，創建people類，和一個controller

package com.soldier.pojo;

/**
 * @Author soldier
 * @Date 2020/3/11 11:18
 * @Version 1.0
 * @Description:
 */
public class People {
    private Long id;
    private String name;
    private String address;

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }
}

package com.soldier.controller;

import com.soldier.pojo.People;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @Author soldier
 * @Date 2020/3/11 11:19
 * @Version 1.0
 * @Description:
 */
@RestController
@RequestMapping("/people")
public class DemoController {

    @RequestMapping("/getPeople")
    public People getPeople(Long id, String name) {
        People people = new People();
        people.setId(id);
        people.setName(name);
        people.setAddress("南寧");
        return people;
    }
}

2、導入spring-box依賴

<!--spring-fox依賴-->
<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>

3、啟動類添加@EnableSwagger2注解

4、啟動項目，訪問Swagger UI

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

 

二、Swagger UI的使用

　　· 訪問 swagger-ui.html 后可以在頁面中看到所有需要生成接口文檔的控制器名稱。

 　　· 每個控制器中間包含多所有控制器方法的各種訪問方式。如果使用的是@RequestMapping 進行映射，將顯示下面的所有請求方式。如果使用@PostMapping 將只有 Post 方式可以能訪問，下面也就只顯示 Post 的一個。

 

 　　· 點擊某個請求方式中 try it out

 　　· 會出現界面要求輸入的值。輸入完成后點擊 Execute 按鈕

 　　· 下面會出現 Request URL 已經不同狀態碼相應回來的結果：

 

三、Swagger的配置

　　可以在項目中創建 SwaggerConfig，進行配置文檔內容。

1、配置基本信息

　　Docket：摘要對象，通過對象配置描述文件的信息。 apiInfo:設置描述文件中 info。參數類型 ApiInfo

　　select()：返回 ApiSelectorBuilder 對象，通過對象調用 build()可以 創建 Docket 對象

　　ApiInfoBuilder：ApiInfo 構建器。

項目中新建一個配置類：

package com.soldier.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @Author soldier
 * @Date 2020/3/11 11:42
 * @Version 1.0
 * @Description: Swagger配置
 */
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket getDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(swaggerDemoApiInfo())
                .select().build();
    }

    private ApiInfo swaggerDemoApiInfo() {
        return new ApiInfoBuilder()
                .contact(new Contact("百度", "www.baidu.com", "[e-mail]"))
                // 標題
                .title("這是Swagger的標題")
                // 描述
                .description("這是Swagger的描述")
                // 版本
                .version("1.0.0")
                .build();
    }
}

　　重啟項目，訪問【http://localhost:8080/swagger-ui.html】，效果如下：

2、設置掃描的包

　　可以通過 apis()方法設置哪個包中內容被掃描

@Bean
public Docket getDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
           .apiInfo(swaggerDemoApiInfo())
           .select()
           .apis(RequestHandlerSelectors.basePackage("com.soldier.controller"))
           .build();
}

3、自定義注解設置不需要生成接口文檔的方法

　　1）自定義注解，名稱可以隨便取

package com.soldier.interfaceDemo;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * @Author soldier
 * @Date 2020/3/11 12:11
 * @Version 1.0
 * @Description: 自定義注解
 */
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface NotIncludeSwagger {
}

　　2）添加規則

　　　　通 過 public ApiSelectorBuilder apis(Predicate<RequestHandler> selector)可以設置生成規則。

　　　　public static <T> Predicate<T> not(Predicate<T> predicate) :表示不 允許的條件。

　　　　withMethodAnnotation：表示此注解是方法級別注解。

@Bean
public Docket getDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
           .apiInfo(swaggerDemoApiInfo())
           .select()
//         .apis(RequestHandlerSelectors.basePackage("com.soldier.controller"))
           // 自定義注解設置不需要生成接口文檔的方法
           .apis(not(withMethodAnnotation(NotIncludeSwagger.class)))
           .build();
}

　　3）添加 @NotIncludeSwagger 注解

　　　　在不需要生成接口文檔的方法上面添加@NotIncludeSwagger 注 解后，該方法將不會被 Swagger 進行生成在接口文檔中。

@NotIncludeSwagger
@RequestMapping("/getPeople2")
public People getPeople2(Long id, String name, String address) {
    People people = new People();
    people.setId(id);
    people.setName(name);
    people.setAddress(address);
    return people;
}

　　　　添加 @NotIncludeSwagger 前的：

　　　　　　

　　　　添加 @NotIncludeSwagger 后的效果：

 　　　　　　

4、設置范圍

　　通過 public ApiSelectorBuilder paths(Predicate<String> selector) 可以設置滿足什么樣規則的 url 被生成接口文檔。可以使用正則表達式 進行匹配。

　　下面例子中表示只有以/demo/開頭的 url 才能被 swagger 生成接口文檔：

　　如何希望全部掃描可以使用 paths(PathSelectors.any())

@Bean
public Docket getDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
           .apiInfo(swaggerDemoApiInfo())
           .select()
//         .apis(RequestHandlerSelectors.basePackage("com.soldier.controller"))
           // 自定義注解設置不需要生成接口文檔的方法
//         .apis(not(withMethodAnnotation(NotIncludeSwagger.class)))
           // 設置范圍：以/demo/開頭的 url 才能被 swagger 生成接口文檔
           // 如何希望全部掃描可以使用 paths(PathSelectors.any())
 .paths(allowPaths())
           .build();
}

private Predicate<String> allowPaths() {
    return or(regex("/demo/.*"));
}

 

四、Swagger2 常用注解

　　1）Api

　　@Api 是類上注解。控制整個類生成接口信息的內容。 tags：類的名稱 可以有多個值 多個值表示多個副本，description:描述 已過時。

@RestController
@RequestMapping("/people")
@Api(tags = {"myDemo"}, description = "DemoController描述")
public class DemoController {

　　在swagger-ui.html 顯示的效果：

 　　2）ApiOperation

　　@ApiOperation 寫在方法上，對方法進行總體描述--》value：接口描述，notes：提示信息

@RequestMapping("/getPeople")
@ApiOperation(value = "接口描述", notes = "提示信息")

　　頁面效果：

　　3）ApiParam

　　@ApiParam 寫在方法參數前面。用於對參數進行描述或說明是否 為必添項等說明--》name：參數名稱，value：參數描述，required：是否是必須

@RequestMapping("/getPeople")
@ApiOperation(value = "接口描述", notes = "提示信息")
public People getPeople(Long id, @ApiParam(value = "姓名 這個是參數描述", required = true) String name) {

　　頁面效果：

 　　4）ApiModel

　　@ApiModel 是類上注解，主要應用 Model，也就是說這個注解一 般都是寫在實體類上--》value：名稱，description：描述

@ApiModel(value = "名稱：人類", description = "描述")
public class People {

　　在swagger-ui.html 顯示的效果：

　　5）ApiModelProperty

　　@ApiModelProperty 可以用在方法或屬性上。用於當對象作為參數時定義這個字段的內容--》value：描述，name：重寫屬性名，required：是否是必須的，example：示例內容，hidden：是否隱藏。

@ApiModelProperty(value = "描述:姓名", name = "重寫屬性名:name", required = true, example = "張三")
private String name;

　　頁面效果：

　　6）ApiIgnore

　　@ApiIgnore 用於方法或類或參數上，表示這個方法或類被忽略。 和之前講解的自定義注解@NotIncludeSwagger 效果類似。只是這個注 解是 Swagger 內置的注解，而@NotIncludeSwagger 是我們自定義的注解。

　　7）ApiImplicitParam

　　@ApiImplicitParam 用在方法上，表示單獨的請求參數，總體功能 和@ApiParam 類似--》name：屬性名，value：描述，required：是否是必須的，paramType：屬性類型，dataType：數據類型

@RequestMapping("/getPeople2")
@ApiImplicitParam(name = "address",value = "地址",required = true,paramType = "query",dataType = "string")
public People getPeople2(Long id, String name, String address) {

　　頁面效果：

 　　如果希望在方法上配置多個參數時，使用 @ApiImplicitParams 進行 配置。示例如下：

@RequestMapping("/getPeople2")
@ApiImplicitParams(value={
       @ApiImplicitParam(name="id",value = "編號",required = true),
       @ApiImplicitParam(name="name",value = "姓名",required = true)
})
public People getPeople2(Long id, String name, String address) {

　　頁面效果：

 

五、源碼地址

點擊前往　　https://github.com/soldiergit/swagger-demo.git