springboot整合knife4j

簡介

官網位址：knife4j

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

一開始項目初衷是為了寫一個增強版本的swagger的前端ui,但是随着項目的發展,面對越來越多的個性化需求,不得不編寫後端Java代碼以滿足新的需求,在swagger-bootstrap-ui的1.8.5~1.9.6版本之間,采用的是後端Java代碼和Ui都混合在一個Jar包裡面的方式提供給開發者使用.這種方式雖說對于內建swagger來說很友善,隻需要引入jar包即可,但是在微服務架構下顯得有些臃腫。

是以,項目正式更名為knife4j,取名knife4j是希望她能像一把匕首一樣小巧,輕量,并且功能強悍,更名也是希望把她做成一個為Swagger接口文檔服務的通用性解決方案,不僅僅隻是專注于前端Ui前端.

後端Java代碼和ui包分離為多個子產品的jar包,以面對在目前微服務架構下,更加友善的使用增強文檔注解(使用SpringCloud微服務項目,隻需要在網關層內建UI的jar包即可,是以分離前後端)。

依賴

<!-- 整合knife4j -->
		<dependency>
			<groupId>com.github.xiaoymin</groupId>
			<artifactId>knife4j-spring-boot-starter</artifactId>
			<version>2.0.8</version>
		</dependency>
           

配置類

//通過配置類整合Swagger2  
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {
 /*引入Knife4j提供的擴充類*/
	@Autowired
	private OpenApiExtensionResolver openApiExtensionResolver;

	@Bean("swagger2ConfigDefault")
	public Docket swagger2ConfigDefault() {
		Docket docket = new Docket(DocumentationType.SWAGGER_2);  //選擇swagger類型
		docket.apiInfo(getApiInfo("我的swaggerDefault", "Default接口文檔"))
		.groupName("default")
		.select()  //  選擇器
		.apis(RequestHandlerSelectors.basePackage("com.conformity.general.controller"))  //  掃描指定包下所有注解
		.paths(PathSelectors.any())  //  指定路徑範圍   這裡表示所有路徑
		.build()		  //  建構swagger文檔對象
		.extensions(openApiExtensionResolver.buildSettingExtensions());
		return docket;
	}
	@Bean("swagger2ConfigCommon")
	public Docket swagger2ConfigCommon() {
		Docket docket = new Docket(DocumentationType.SWAGGER_2);  //選擇swagger類型
		docket.apiInfo(getApiInfo("我的swaggerCommon", "Common接口文檔"))
		.groupName("Common")
		.select()  //  選擇器
		.apis(RequestHandlerSelectors.basePackage("com.conformity.general.controller"))  //  掃描指定包下所有注解
		.paths(PathSelectors.any())  //  指定路徑範圍   這裡表示所有路徑
		.build()					//  建構swagger文檔對象
		.extensions(openApiExtensionResolver.buildSettingExtensions());
		return docket;
	}

	private ApiInfo getApiInfo(String title,String description) {
		return new ApiInfoBuilder()  //設定文檔上下文資訊
				.title(title)   //  文檔标題
				.description(description)		//  簡介
				.version("1.0")				//  版本
				// 設定聯系人  ： 作者   網站位址  郵箱
				.contact(new Contact("lsx", "https://gitee.com/buluozhimu", "[email protected]"))  
				// 服務條款連結
				.termsOfServiceUrl("https://gitee.com/buluozhimu")
				// 認證許可
				.license("my swagger -- test")
				// 認證許可連結
				.licenseUrl("https://www.baidu.com")
				.build();  //  建構上下文對象a
	}
}
           

界面

@Bean(“swagger2ConfigDefault”)和@Bean(“swagger2ConfigCommon”) 分為兩個組，通過.groupName()方法進行分組

ApiInfo：建構首頁資訊

yml配置

knife4j:
  enable: true  #開啟增強配置
  production: false #開啟生産環境屏蔽
  basic:  #基本的登入認證
    enable: false
    password: lsx
    username: lsx
    #自定義footer
  setting:
    enableFooter: false
    enableFooterCustom: true
    footerCustomContent: Apache License 2.0 | Copyright  2021-[英雄聯盟](https://gitee.com/buluozhimu)
           

常用注解

• @Api(tags = {“測試Controller”}) 給controller 起别名 類注解
• @ApiOperation(“測試demo”) 方法的描述
• @ApiParam(name = “a”,value = “使用者名”,required = true) 對參數的描述
• @ApiIgnore 忽略 标注方法 或者 參數 則不生成對應文檔
• @ApiImplicitParams

@ApiImplicitParams({   	//描述方法上的參數  功能和ApiParam 差不多  差别在于作用于方法上
	         	 @ApiImplicitParam(name = "id", value = "主鍵ID", required = true, paramType = "query"),           
			})
           

• @ApiModel(value = “User”,description = “使用者實體”) 标注于實體類
• @ApiModelProperty(value = “主鍵”,name = “id”) 标注與實體類的屬性

• @ApiOperationSupport(author = “lsx”,order = 1) 标注方法上 添加作者 接口排序（Knife4j增強注解：需要在application.yml中開啟增強功能）

  示例代碼

@RestController
@RequestMapping(value = "/swagger",method = RequestMethod.POST)
@Api(tags = "swaggerController")
public class SwaggerController {
	
	@RequestMapping("/demo1")
	@ApiOperation("寫注釋我是認真的")
	@ApiOperationSupport(author = "lsx",order = 1)
	@ApiImplicitParams({   
        @ApiImplicitParam(name = "username", value = "使用者名", required = true,paramType = "query"),
        @ApiImplicitParam(name = "password", value = "密碼", required = true, paramType = "query"),
        @ApiImplicitParam(name = "createTime", value = "建立時間", required = true, paramType = "query"),
	})
	public SwaggerTestEntity demo1(@ApiIgnore SwaggerTestEntity user,@ApiParam(name = "videoFile",value = "檔案上傳") MultipartFile videoFile) {
		SwaggerTestEntity userEntity = new SwaggerTestEntity()
		.setCrateTime(new Date())
		.setId("uuid")
		.setUsername(user.getUsername())
		.setPassword(user.getPassword());
		return userEntity;
	}
	
}
           

@Data
@Accessors(chain = true)
@ApiModel(value = "SwaggerTestEntity",description = "swagger測試實體")
public class SwaggerTestEntity implements Serializable{
	private static final long serialVersionUID = 1L;

	@ApiModelProperty(value = "主鍵",name = "id")
	private String id;

	@ApiModelProperty(value = "使用者名",name = "username")
	private String username;

	@ApiModelProperty(value = "密碼",name = "password")
	private String password;


	@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
	@JsonFormat(pattern="yyyy-MM-dd HH:mm:ss",timezone = "GMT+8")
	@ApiModelProperty(value = "建立日期",name = "crateTime")
	private Date crateTime;

}
           

接口界面