關(guān)于knife4j的使用及配置

更新時(shí)間：2023年06月26日 08:38:48 作者：_不負(fù)時(shí)光

這篇文章主要介紹了關(guān)于knife4j的使用及配置，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方，望不吝賜教

knife4j的使用配置

關(guān)鍵詞：swagger、springfox、swagger-bootstrap-ui

說(shuō)明：一款更加美化，實(shí)用、方便生成漂亮離線文檔的接口文檔工具

第一步

引入依賴

?<dependency>
? ? ? ? ? ? <groupId>com.github.xiaoymin</groupId>
? ? ? ? ? ? <artifactId>knife4j-spring-boot-starter</artifactId>
? ? ? ? ? ? <version>2.0.8</version>
? ? ? ? ? ? <type>pom</type>
? ? ? ? </dependency>

第二步

配置swagger

@EnableSwagger2
@Component
public class Swagger2 {
? ? @Bean
? ? public Docket createRestApi() {
? ? ? ? return new Docket(DocumentationType.SWAGGER_2)
? ? ? ? ? ? ? ? .groupName("default")
? ? ? ? ? ? ? ? .apiInfo(apiInfo())
? ? ? ? ? ? ? ? .select()
? ? ? ? ? ? ? ? .apis(RequestHandlerSelectors.basePackage("xxx.controller"))
? ? ? ? ? ? ? ? .paths(PathSelectors.any())
? ? ? ? ? ? ? ? .build();
? ? }
? ? private ApiInfo apiInfo() {
? ? ? ? return new ApiInfoBuilder()
? ? ? ? ? ? ? ? .title("xxx接口說(shuō)明")
? ? ? ? ? ? ? ? .description("OpenAPI規(guī)范接口描述")
? ? ? ? ? ? ? ? .version("v1.0")
? ? ? ? ? ? ? ? .contact(new Contact("xxx公司", "http://xxx.com/", "xxx@xxx.com"))
? ? ? ? ? ? ? ? .license("License")
? ? ? ? ? ? ? ? .licenseUrl("http://xxx.com/")
? ? ? ? ? ? ? ? .build();
? ? }
}

第三步

控制器加swagger-ui 注解（略）

第四步

啟動(dòng)訪問(wèn)

啟動(dòng)springboot 項(xiàng)目

訪問(wèn)：localhost:port/doc.html

knife4j 簡(jiǎn)單使用

Swagger作為一款A(yù)PI文檔生成工具，雖然功能已經(jīng)很完善了，但是還是有些不足的地方。

knife4j簡(jiǎn)介

knife4j完全遵循了springfox-swagger中的使用方式，并在此基礎(chǔ)上做了增強(qiáng)功能，如果用過(guò)Swagger，可以無(wú)縫切換到knife4j。

快速開(kāi)始

1、在pom.xml中增加knife4j的相關(guān)依賴

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

2、在Swagger2Config中增加一個(gè)@EnableKnife4j注解，該注解可以開(kāi)啟knife4j的增強(qiáng)功能

/**
?* Swagger2API文檔的配置
?*/
@Configuration
@EnableSwagger2
@EnableKnife4j
public class Swagger2Config {
}

3、運(yùn)行我們的SpringBoot應(yīng)用，訪問(wèn)API文檔地址即可查看：

http://localhost:8080/doc.html

功能特點(diǎn)

對(duì)比下Swagger，看看使用knife4j和它有啥不同之處

1、返回結(jié)果集支持折疊，方便查看

2、請(qǐng)求參數(shù)有JSON校驗(yàn)功能

3、 knife4j支持導(dǎo)出離線文檔，方便發(fā)送給別人，支持Markdown格式

直接選擇文檔管理->離線文檔功能，然后選擇下載Markdown即可

4、忽略參數(shù)屬性

有時(shí)候我們創(chuàng)建和修改的接口會(huì)使用同一個(gè)對(duì)象作為請(qǐng)求參數(shù)，但是我們創(chuàng)建的時(shí)候并不需要id，而修改的時(shí)候會(huì)需要id，此時(shí)我們可以忽略id這個(gè)屬性。

比如這里的創(chuàng)建商品接口，id、商品數(shù)量、商品評(píng)論數(shù)量都可以讓后臺(tái)接口生成無(wú)需傳遞，可以使用knife4j提供的@ApiOperationSupport注解來(lái)忽略這些屬性

@Api(tags = "PmsBrandController", description = "商品品牌管理")
@Controller
@RequestMapping("/brand")
public class PmsBrandController {
? ? @Autowired
? ? private PmsBrandService brandService;
? ? private static final Logger LOGGER = LoggerFactory.getLogger(PmsBrandController.class);
? ? @ApiOperation("添加品牌")
? ? @ApiOperationSupport(ignoreParameters = {"id","productCount","productCommentCount"})
? ? @RequestMapping(value = "/create", method = RequestMethod.POST)
? ? @ResponseBody
? ? public CommonResult createBrand(@RequestBody PmsBrand pmsBrand) {
? ? ? ? CommonResult commonResult;
? ? ? ? int count = brandService.createBrand(pmsBrand);
? ? ? ? if (count == 1) {
? ? ? ? ? ? commonResult = CommonResult.success(pmsBrand);
? ? ? ? ? ? LOGGER.debug("createBrand success:{}", pmsBrand);
? ? ? ? } else {
? ? ? ? ? ? commonResult = CommonResult.failed("操作失敗");
? ? ? ? ? ? LOGGER.debug("createBrand failed:{}", pmsBrand);
? ? ? ? }
? ? ? ? return commonResult;
? ? }
}