关于java:给Swagger换了个新皮肤瞬间高大上了

SpringBoot实战电商我的项目mall（39k+star）地址：https://github.com/macrozheng/mall

摘要

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;
    }
}

• 此时查看接口文档时，发现这三个属性曾经隐没，这样前端开发查看接口文档时就不会感觉你定义无用参数了，是不很很好的性能！

参考资料

官网文档：https://doc.xiaominfo.com/guide/

我的项目源码地址

https://github.com/macrozheng…

文章继续更新，能够微信搜一搜「 macrozheng 」第一工夫浏览，回复【实战教程】获取mall全套原创教程。本文 GitHub https://github.com/macrozheng/mall-learning 曾经收录，欢送Star。