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

目錄

緣由

原生Swagger

Knife4J

緣由

接口文檔想必是許多開發小伙伴的噩夢，不僅要寫詳細，還要及時維護文檔與后端代碼保持一致，稍有沒及時更新接口文檔，前端同學肯定會抱怨后端同學給的文檔與實際情況不一致。

于是，引入了Swagger組件，它實現了代碼即文檔，后端只管寫代碼，只需要通過幾個注解，會自動生成接口文檔，前端同學可在線訪問。

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

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

原生Swagger

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

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

io.springfox springfox-swagger2 2.9.2 io.springfox springfox-swagger-ui 2.9.2

1

2

3

4

5

6

7

8

9

10

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

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

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

@Api：作用于類上，標識此類是Swagger的資源。

@ApiOperation：主要作用于方法上，用于對一個接口進行說明。

@ApiParam：用于方法，參數，字段上，用于對參數進行說明。

@ApiModel：作用于類上，主要用于實體類當接口參數時使用，對實體類進行說明。

@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; }

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

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 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<>(); } }

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

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依賴，即可使用。

com.github.xiaoymin knife4j-spring-boot-starter 3.0.2

1

2

3

4

5

然后Swagger配置類還是和原生的一模一樣，即上面介紹過的Swagger2Config類，注解的使用也是和原生的完全一樣。只是項目啟動后，接口文檔界面的訪問地址不一樣：

原生Swagger：http://ip:port/swagger-ui.html#/

Knife4J：http://ip:port/doc.html#/

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

當我們打開一個接口，顯示的界面信息更全了，而且分為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

web前端

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。