关于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。