前端嫌棄原生Swagger介面太low，於是我給她開通了超級VIP

陳皮的JavaLib發表於2021-03-28
前端Swagger

緣由

介面文件想必是許多開發小夥伴的噩夢，不僅要寫詳細，還要及時維護文件與後端程式碼保持一致，稍有沒及時更新介面文件，前端同學肯定會抱怨後端同學給的文件與實際情況不一致。

於是，引入了Swagger元件，它實現了程式碼即文件，後端只管寫程式碼，只需要通過幾個註解，會自動生成介面文件，前端同學可線上訪問。

但是，對介面審美有要求的前端同學，又吐槽Swagger原生介面太low了，而且功能還少。

有壓迫就有反抗，後端肯定不服，既然你嫌棄原生Swagger太low，那就給你開通超級VIP - knife4j。

原生Swagger

Springboot整合Swagger，其實很簡單，主要是使用常用的幾個註解而已。因為在面試他人的過程中，還是有不少人沒使用過Swagger，所以這裡簡單介紹下。

首先在Spingboot工程中引入Swagger依賴，主要是2個，如下：

<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>

編寫Swagger配置類，配置項名都簡單易懂，可根據自己情況修改配置，注意一點是apis方法是指定要掃描的包路徑，一定要寫自己專案的。

package com.nobody.config;
​
import java.util.ArrayList;
import java.util.List;
​
import org.springframework.beans.factory.annotation.Value;
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.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
​
@Configuration
@EnableSwagger2
public class Swagger2Config {
​
    @Value("${swagger.enable:true}")
    private boolean swaggerEnable;
​
    @Bean
    public Docket createApi() {
        // 全域性引數
        List<Parameter> pars = new ArrayList<>();
        return new Docket(DocumentationType.SWAGGER_2).enable(swaggerEnable).apiInfo(apiInfo())
                .select().apis(RequestHandlerSelectors.basePackage("com.nobody"))
                .paths(PathSelectors.any()).build().globalOperationParameters(pars);
    }
​
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("XX服務後端API").description("XX服務專用API，其他系統請勿呼叫！")
                .version("1.0").termsOfServiceUrl("https://nobody.com")
                .contact(new Contact("陳皮", "https://nobody.com", "chenpi@qq.com")).build();
    }
}

下面講解幾個常用的註解，以及如何使用，更多註解以及詳細使用可以參考官方文件。

  1. @Api：作用於類上，標識此類是Swagger的資源。
  2. @ApiOperation：主要作用於方法上，用於對一個介面進行說明。
  3. @ApiParam：用於方法，引數，欄位上，用於對引數進行說明。
  4. @ApiModel：作用於類上，主要用於實體類當介面引數時使用，對實體類進行說明。
  5. @ApiModelProperty：作用於方法和欄位上，一般用於實體類的屬性說明。
package com.nobody.dto;
​
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
​
/**
 * @Description
 * @Author Mr.nobody
 * @Date 2021/3/28
 * @Version 1.0
 */
@ApiModel(value = "管理員實體")
@Data
public class AdminDTO {
    @ApiModelProperty(value = "使用者ID", required = true, example = "1548w4dwf7as1a21cv4")
    private String personId;
    @ApiModelProperty(value = "使用者名稱", example = "陳皮")
    private String name;
    @ApiModelProperty(value = "使用者年齡", required = true, example = "18")
    private Integer age;
}

package com.nobody.controller;
​
import com.nobody.dto.AdminDTO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
​
import java.util.ArrayList;
import java.util.List;
/**
 * @Description
 * @Author Mr.nobody
 * @Date 2021/3/27
 * @Version 1.0
 */
@Api(tags = {"管理員相關"})
@RestController
@RequestMapping("admin")
public class AdminController {
​
    @ApiOperation(value = "新增管理員", notes = "注意：只有管理員許可權才能新增管理員", produces = "application/json",
            consumes = "application/json")
    @PostMapping("add")
    public AdminDTO add(@ApiParam(value = "引數體", required = true) @RequestBody AdminDTO adminDTO) {
        return adminDTO;
    }
​
    @ApiOperation(value = "管理員列表", notes = "注意：只有管理員許可權才能獲取管理員列表", produces = "application/json")
    @GetMapping("list")
    public List<AdminDTO> list(
            @ApiParam(value = "頁碼，從1開始，1，2，3...", required = true,
                    example = "1") @RequestParam Integer pageIndex,
            @ApiParam(value = "頁量", required = true,
                    example = "10") @RequestParam Integer pageSize) {
        return new ArrayList<>();
    }
}

Knife4J

Knife4j的前身是swagger-bootstrap-ui,前身swagger-bootstrap-ui是一個純swagger-ui的ui皮膚專案。

目前已經發行的Knife4j版本，其本身已經引入了springfox，所以我們不需要再單獨引入Springfox的具體版本，否則會導致版本衝突。

注意，使用Knife4j2.0.6及以上的版本，SpringBoot的版本必須大於等於2.2.x。

Knife4J的使用極其簡單，因為Knife4J將其封裝成一個啟動器starter，一個可拔插式的元件，只需要引入starter依賴，即可使用。

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-boot-starter</artifactId>
  <version>3.0.2</version>
</dependency>

然後Swagger配置類還是和原生的一模一樣，即上面介紹過的Swagger2Config類，註解的使用也是和原生的完全一樣。只是專案啟動後，介面文件介面的訪問地址不一樣：

是不是介面比原生的好看多了，還是保持著簡潔美觀，但是功能更多了。

當我們開啟一個介面，顯示的介面資訊更全了，而且分為3個頁面，文件，除錯和Open，​如下所示：

支援全域性搜尋，不用在眾多介面中一個一個查詢，節省時間。

Knife4j 提供全域性引數Debug功能，目前預設提供header(請求頭)、query(form)兩種方式的入參。新增全域性引數後，預設Debug除錯tab頁會帶上該引數。

Knife4j提供匯出4種格式的離線文件(Html/Markdown/Word/OpenAPI)

啟用個性化配置後,介面Tab標籤需關閉後重新開啟或者重新整理當前頁面。

更多Knife4J的詳細介紹，可以檢視官方介紹文件，很詳細​。​https://xiaoym.gitee.io/knife4j/documentation/description.html

相關文章