给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项目全套学习教程连载中，关注公众号第一时间获取。