Swagger以及knife4j基本使用

• Swagger以及knife4j基本使用
  • Swagger 介紹：
    • Restful 面向資源
    • SpringBoot使用swagger
  • Knife4j --Swagger增強工具

Swagger 介紹：

官網：https://swagger.io/

Swagger 是一個規范和完整的框架，用于生成、描述、呼叫和可視化RESTful風格的 Web 服務

Restful 面向資源

RESTful是一種架構的規范與約束、原則，符合這種規范的架構就是RESTful架構

Rest是web服務的一種架構風格；使用HTTP，URI，XML，JSON，HTML等廣泛流行的標準和協議；輕量級，跨平臺，跨語言的架構設計，它是一種設計風格，不是一種標準，是一種思想，

說明：

冪等性：對同一REST介面多次訪問，得到的資源狀態是相同的

安全性：對該REST介面訪問，不會使服務端資源狀態發生改變

優點：

• 透明性 --暴露資源存在（資源操作通過http本身語意進行描述，不用單獨描述）

• 充分利用HTTP協議本身語意

• 無狀態 --在呼叫一個介面時可以不用考慮背景關系，不用考慮當前狀態降低了復雜度

• HTTP本身提供了豐富的內容協商手段（快取，資源修改的樂觀并發控制等可以通過與業務無關的中間件實作）

SpringBoot使用swagger

1. 匯入依賴

• 2版本

<!--swagger依賴-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--swagger ui-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>

• 3.0版本

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>

2. 撰寫swagger組態檔

@Configuration
@EnableSwagger2  //開啟Swagger2
public class Swagger2Config {
    /**
     * 創建API應用
     * apiInfo() 增加API相關資訊
     * 通過select()函式回傳一個ApiSelectorBuilder實體,用來控制哪些介面暴露給Swagger來展現，
     * 指定掃描的包路徑來定義指定要建立API的目錄，
     * @return
     */
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(adminApiInfo())
                 //.enable(false) //enable是否啟動Swagger 如果為false，則swagger不能在瀏覽器中訪問
                .groupName("adminApi")
                .select()
                //RequestHandlerSelectors 配置要掃描介面的方式
                //basePackage: 指定要掃描的包
                //any()：掃描全部
                //none()不掃描
                //withClassAnnotation: 掃描類上的注解，引數為一個注解的反射物件
                //withMethodeAnnotation: 掃描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
                //只顯示admin下面的路徑
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
                .build();
    }

    private ApiInfo adminApiInfo(){
        return new ApiInfoBuilder()
                .title("api檔案")
                .description("系統介面描述")
                .version("1.0")
                //作者資訊
                .contact(new Contact("張三","http://baidu.com","[email protected]"))
                .build();
    }
}

3. 撰寫介面請求并運行

訪問方式（本地）：http://localhost:8080/swagger-ui.html

使用：

• 物體類：

  • @ApiModel("用戶物體類")
    public class User{
    
        @ApiModelProperty("用戶名")
        public String username;
    }
    

• 介面方法，引數：

  • @RestController
    public class UserController{
        
        @ApiOperation("User控制類")
        @GetMapping(value="https://www.cnblogs.com/user")
        public String getUser(@ApiParam("用戶名")String username){
        return "名字為："+username;
    } 
    }
    

常用注解：

@Api：修飾整個類，描述Controller的作用,放在類上

@ApiOperation：描述一個類的一個方法，或者說一個介面

@ApiParam：單個引數描述

@ApiModel：用物件來接收引數

@ApiProperty：用物件接收引數時，描述物件的一個欄位

@ApiResponses：HTTP回應整體描述

@ApiResponse：HTTP回應其中1個描述

@ApiIgnore：使用該注解忽略這個API

@ApiError ：發生錯誤回傳的資訊

@ApiImplicitParams：描述由多個 @ApiImplicitParam 注解的引陣列成的請求引數串列

@ApiImplicitParam：描述一個請求引數，可以配置引數的中文含義，還可以給引數設定默認值
//eg:
    @ApiImplicitParam(name="username",value="https://www.cnblogs.com/prosperous-ending-0925/archive/2022/08/22/用戶名",required=true)

Knife4j --Swagger增強工具

使用Knife4j2.06以上版本，springboot版本必須大于等于2.2.x

作用

• 可以搜索介面名稱快速定位介面(搜索功能)

• 可以下載markdown、HTML、word 等格式檔案(下載功能)

1. 引入依賴

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

2. 添加SwaggerConfiguration作為Swagger2的配置類

@Configuration
@EnableSwagger2
@EnableKnife4j
//@EnableSwagger2WebMvc 2.6以上報空指標例外則需要添加
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)      // 選擇swagger2版本
                .apiInfo(apiInfo())         //定義api檔案匯總資訊
                .select()
                .apis(RequestHandlerSelectors
                        .basePackage("com.example"))  // 指定生成api檔案的包
                .paths(PathSelectors.any())     // 指定所有路徑
                .build();
    }

    /**
     * 構建檔案api資訊
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("")     // 檔案標題
                .contact(new Contact("", "", ""))   //聯系人資訊
                .description("")      //描述
                .version("1.0.1")     //檔案版本號
                .termsOfServiceUrl("")     //網站地址
                .build();
    }
}

3. 實作生產環境關閉文黨澩

spring: 
  profiles: prod #指定環境
knife4j:
   production: true #開啟屏蔽文黨澩

4. 實作介面排序

• 針對不同Controller排序：Controller上標注@ApiSupport(order = 序號)
• 針對同一個Controller中的不同方法排序：同一個Controller不同介面方法上標注@ApiOperationSupport(order = 序號)

注：更多詳細配置可查看CSDN博主：swagger檔案增強工具knife4j使用詳解_baobao555#的博客-CSDN博客_knife4j swagger

標籤：其他

上一篇：Mybatis 懶加載使用及原始碼分析

下一篇：多道技術、同步異步和阻塞非阻塞