springboot集成swagger之knife4j實戰（升級版）

本文轉載自查看原文 2021-04-01 09:23 2324 swagger

官方文檔鏈接：https://doc.xiaominfo.com/

一、Knifej和swagger-bootstrap-ui對比

Knife4j在更名之前，原來的名稱是叫swagger-bootstrap-ui，這是兩種不一樣風格的ui顯示，將原來的藍色變成炫酷的黑色模式；
Knifej是使用knife4j-spring-boot-starter的風格來編寫的，可以將配置項寫在配置文件中，這些配置項提供了許多增強功能，可以更好的整合springboot、springcloud；
Knifej執行更新，為了更平滑的演進，而swagger-bootstrap-ui已停更；

軟件	開發語言&框架	狀態	最后版本	風格
Knife4j	Java、JavaScript、Vue	持續更新中	無	1.9.6版本是藍色，后續版本為黑色
swagger-bootstrap-ui	Java、JavaScript、jQuery	停更	1.9.6	藍色

二、版本分析

Knife4j底層依賴springfox，因此無需再單獨引入Springfox的具體版本，且兩者有對應的版本要求，否則會產生很多沖突；
使用Knife4j2.0.6及以上的版本，Spring Boot的版本必須大於等於2.2.x；

版本	說明
1.9.6	藍色皮膚風格，增加更多后端模塊
2.0~2.0.5	Ui重寫，藍色背景變成黑色，底層依賴的springfox框架版本是2.9.2
2.0.6~	底層springfox框架版本升級知2.10.5,OpenAPI規范是v2
3.0~	底層依賴springfox框架版本升級至3.0.3,OpenAPI規范是v3

三、訪問方式：

http://{ip}:{port}/doc.html，訪問方式和之前的保持一致，如果項目中配置攔截器等，需要放開doc.html靜態資源

四、springboot整合步驟(以2.0.6版本為例，但是也會說明各個版本之間的區別)

(1) 添加依賴

<!-- swagger-ui Knife4j，只需要導入這一個依賴就好了，無需在添加spring-fox的依賴 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>${knife4j.version}</version>
</dependency>

(2) 編寫配置

2.0.6及以上版本，使用@EnableSwagger2WebMvc注解開啟，而2.0.6之前版本是使用@EnableSwagger2注解，和swagger-bootstrap-ui是一樣的；
如果不想編寫配置類也可以，將@EnableSwagger2WebMvc標注在啟動類上即可，就完成入門級別的整合。

package com.ruyidan.knife4j.config;

import java.util.ArrayList;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
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.EnableSwagger2WebMvc;

/**
 * @ClassName: SwaggerConfig
 * @Description:
 * @Author: dangbo
 * @Date: 2021/3/31 14:13
 * @Version
 */
@Configuration
@EnableSwagger2WebMvc
// @EnableKnife4j    // 因為在配置文件中配置，因此不需要這個注解了
public class Knife4jConfig {

    @Autowired
    private Environment environment;

    @Bean
    public Docket docket() {
        // 設置顯示的swagger環境信息
        Profiles profiles = Profiles.of("dev", "test");
        // 判斷是否處在自己設定的環境當中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("分組名稱")  // 配置api文檔的分組
                .enable(flag)  // 配置是否開啟swagger
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ruyidan")) //配置掃描路徑
                .paths(PathSelectors.any()) // 配置過濾哪些
                .build();
    }
    // api基本信息
    private ApiInfo apiInfo() {
        return new ApiInfo("dxiaodang's swagger",
                "測試swagger-ui",
                "v1.0",
                "http://mail.qq.com",
                new Contact("dangbo", "http://mail.qq.com", "145xxxxx@qq.com"),  //作者信息
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

(3) 訪問測試

---------------------------------------------------------------------------------------------------------------------------------------------
簡單入門的springboot整合knife4j就完成了，如果不需要使用增強功能，到此就結束了；后續介紹常用的Kni4j的增強功能！！！
---------------------------------------------------------------------------------------------------------------------------------------------

(4) 開啟增強功能

knife4j 1.9.6版本不支持增強功能；之后的版本才支持增強功能；
knife4j 2.0.6及以上版本，Spring Boot的版本必須大於等於2.2.x，且springfox版本要對應；

（第一步）

使用注解@EnableKnife4j標注；或者在配置文件knife4j.enable=true（2.0.6及以上版本才支持），開啟Knife4j增強模式，默認是false；

（第二步）

如果在配置文件中使用個性化文檔(knife4j.documents)和個性化設置(knife4j.setting),還需要在創建Docket對象時調用Knife4j提供的擴展Extesions進行賦值
buildExtensions方法需要傳入分組名稱,該分組名稱主要是為了區分開發者在構建自定義文檔時，在不同的Docket邏輯分組下進行區別顯示

package com.ruyidan.knife4j.config;

import java.util.ArrayList;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
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.EnableSwagger2WebMvc;

/**
 * @ClassName: SwaggerConfig
 * @Description:
 * @Author: dangbo
 * @Date: 2021/3/31 14:13
 * @Version
 */
@Configuration
@EnableSwagger2WebMvc
@EnableKnife4j
public class Knife4jConfig {

    /*引入Knife4j提供的擴展類*/
    @Autowired
    private OpenApiExtensionResolver openApiExtensionResolver;

    @Autowired
    private Environment environment;

    @Bean
    public Docket docket() {
        // 設置顯示的swagger環境信息
        Profiles profiles = Profiles.of("dev", "test");
        // 判斷是否處在自己設定的環境當中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("dxiaodang's group")  // 配置api文檔的分組
                .enable(flag)  // 配置是否開啟swagger
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ruyidan")) //配置掃描路徑
                .paths(PathSelectors.any()) // 配置過濾哪些
                .build()
                // 為了區分開發者在構建自定義文檔時，在不同的Docket邏輯分組下進行區別顯示
                .extensions(openApiExtensionResolver.buildExtensions("md"));
    }

    // api基本信息
    private ApiInfo apiInfo() {
        return new ApiInfo("dxiaodang's swagger",
                "測試knife4j-ui",
                "v1.0",
                "http://mail.qq.com",
                new Contact("dangbo", "http://mail.qq.com", "145xxxxx@qq.com"),  //作者信息
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

(5) 編寫配置

所有的配置項都在這里，如果說自己使用的版本沒有生效，可能就是該版本還未支持，可以升級版本嘗試
有些增強功能還需要增加注解：比如增加作者信息，使用@ApiOperationSupport和@ApiSupport
有些增強功能是有默認值的，比如i18n國際化默認為zh_CN，顯示OpenAPI規范為true；
有些增強功能是不需要在yml額外配置。只要開始增強功能，就支持，比如導出離線文檔，搜索功能；

knife4j:
  enable: true    # 是否開啟Knife4j增強模式，默認值為false
  cors: false     # 是否開啟一個默認的跨域配置,該功能配合自定義Host使用，默認值為false
  production: false     # 對Knife4j提供的資源提供BasicHttp校驗,保護文檔
  basic:
    enable: true       # 關閉BasicHttp功能，默認為false
    username: dangbo    # basic用戶名
    password: dangbo    # basic密碼
  documents:            # 自定義文檔集合，該屬性是數組
    -
      group: md版本    # 所屬分組
      name: 測試分組1    # 類似於接口中的tag,對於自定義文檔的分組
      locations: classpath:md/*     # markdown文件路徑,可以是一個文件夾(classpath:markdowns/*)，也可以是單個文件(classpath:md/sign.md)
    -
      group: markdown版本
      name: 測試分組2
      locations: classpath:markdown/*
  setting:            # 前端Ui的個性化配置屬性
    language: en-US                   # Ui默認顯示語言,目前主要有兩種:中文(zh-CN)、英文(en-US)，默認為中文
    enableSwaggerModels: true         # 是否顯示界面中SwaggerModel功能，默認是true
    enableDocumentManage: true        # 是否顯示界面中"文檔管理"功能，默認是true
    swaggerModelName: 實體類列表       # 重命名SwaggerModel名稱
    enableVersion: false              # 是否開啟界面中對某接口的版本控制,如果開啟，后端變化后Ui界面會存在小藍點
    enableReloadCacheParameter: false # 是否在每個Debug調試欄后顯示刷新變量按鈕,默認不顯示
    enableAfterScript: true           # 調試Tab是否顯示AfterScript功能,默認開啟
    enableFilterMultipartApiMethodType: POST    # 具體接口的過濾類型，默認為POST
    enableFilterMultipartApis: false  # 針對RequestMapping的接口請求類型,在不指定參數類型的情況下,如果不過濾,默認會顯示7個類型的接口地址參數,如果開啟此配置,默認展示一個Post類型的接口地址
    enableRequestCache: true          # 是否開啟請求參數緩存
    enableHost: false                 # 是否啟用Host，默認為false
    enableHostText: 192.168.0.193:8000                # 主機描述
    enableHomeCustom: true            # 是否開啟自定義主頁內容，默認為false
    homeCustomLocation: classpath:markdown/home.md    # 主頁內容Markdown文件路徑
    enableSearch: false             # 是否禁用Ui界面中的搜索框，默認為false
    enableFooter: false             # 是否顯示Footer，默認為true
    enableFooterCustom: true        # 是否開啟自定義Footer，默認為false
    footerCustomContent: Apache License 2.0           # 自定義Footer內容
    enableDynamicParameter: false   # 是否開啟動態參數調試功能，默認為false
    enableDebug: true               # 啟用調試，默認為true
    enableOpenApi: false            # 顯示OpenAPI規范，默認為true
    enableGroup: true               # 顯示服務分組，默認為true

(6) 驗證增強功能（列舉幾個，想嘗試的朋友可以看看官方文檔）

開啟登錄

默認為英文

支持自定義文檔顯示

---------------------------------------------------------------------------------------------------------------------------------------------
如果大家想看Spring Cloud整合Knife4j，可以留言，我花時間整理下分享給大家
本次分享就到這兒了，如果有疑問的話，歡迎大家一起探討！

免責聲明！

本站轉載的文章為個人學習借鑒使用，本站對版權不負任何法律責任。如果侵犯了您的隱私權益，請聯系本站郵箱yoyou2525@163.com刪除。

猜您在找 SpringBoot集成Swagger以及Knife4j SpringBoot 集成 knife4j (Swagger2) SpringBoot2.x集成swagger2/knife4j swagger集成以及knife4j的增強 knife4j swagger Springboot 基於swagger 整合Knife4j SpringBoot2.x集成knife4j 集成Knife4j SpringBoot集成Swagger-Bootstrap-UI（已改名為Knife4j） SpringBoot配置knife4j版的Swagger打開doc.html頁面404