給Swagger換了個新皮膚，瞬間高大上了！

SpringBoot實戰電商項目mall（35k+star）地址：github.com/macrozheng/…

摘要

Swagger做爲一款API文檔生成工具，雖然功能已經很完善了，可是仍是有些不足的地方。偶然發現knife4j彌補了這些不足，賦予了Swagger更多的功能，今天咱們來說下它的使用方法。

knife4j簡介

knife4j是springfox-swagger的加強UI實現，爲Java開發者在使用Swagger的時候，提供了簡潔、強大的接口文檔體驗。knife4j徹底遵循了springfox-swagger中的使用方式，並在此基礎上作了加強功能，若是你用過Swagger，你就能夠無縫切換到knife4j。

快速開始

接下來咱們來介紹下如何在SpringBoot中使用knife4j，僅需兩步便可！

• 在pom.xml中增長knife4j的相關依賴；

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

• 在Swagger2Config中增長一個@EnableKnife4j註解，該註解能夠開啓knife4j的加強功能；

/** * Swagger2API文檔的配置 */
@Configuration
@EnableSwagger2
@EnableKnife4j
public class Swagger2Config {
    
}
複製代碼

• 運行咱們的SpringBoot應用，訪問API文檔地址便可查看：http://localhost:8088/doc.html

功能特色

接下來咱們對比下Swagger，看看使用knife4j和它有啥不一樣之處！

JSON功能加強

平時一直使用Swagger，可是Swagger的JSON支持一直不是很好，JSON不能摺疊，太長無法看，傳JSON格式參數時，沒有參數校驗功能。這些痛點，在knife4j上都獲得瞭解決。

• 返回結果集支持摺疊，方便查看；

• 請求參數有JSON校驗功能。

登陸認證

knife4j也支持在頭部添加Token，用於登陸認證使用。

• 首先在Authorize功能中添加登陸返回的Token；

• 以後在每一個接口中就能夠看到已經在請求頭中攜帶了Token信息。

離線文檔

knife4j支持導出離線文檔，方便發送給別人，支持Markdown格式。

• 直接選擇文檔管理->離線文檔功能，而後選擇下載Markdown便可；

• 咱們來查看下導出的Markdown離線文檔，仍是很詳細的。

全局參數

knife4j支持臨時設置全局參數，支持兩種類型query(表單)、header(請求頭)。

• 好比咱們想要在全部請求頭中加入一個參數appType來區分是android仍是ios調用，能夠在全局參數中添加；

• 此時再調用接口時，就會包含appType這個請求頭了。

忽略參數屬性

有時候咱們建立和修改的接口會使用同一個對象做爲請求參數，可是咱們建立的時候並不須要id，而修改的時候會須要id，此時咱們能夠忽略id這個屬性。

• 好比這裏的建立商品接口，id、商品數量、商品評論數量均可以讓後臺接口生成無需傳遞，能夠使用knife4j提供的@ApiOperationSupport註解來忽略這些屬性；

/** * 品牌管理Controller * Created by macro on 2019/4/19. */
@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;
    }
}
複製代碼

• 此時查看接口文檔時，發現這三個屬性已經消失，這樣前端開發查看接口文檔時就不會以爲你定義無用參數了，是不很很好的功能！

參考資料

官方文檔：doc.xiaominfo.com/guide/

項目源碼地址

github.com/macrozheng/…

公衆號

mall項目全套學習教程連載中，關注公衆號第一時間獲取。