I changed Swagger to a new skin, and instantly became taller

Author: macrozheng

Original link: https://mp.weixin.qq.com/s/XbBD0E136F72gI6OkVIZeA

Swagger, as an API document generation tool, although the function is very complete, there are still some shortcomings. I accidentally found that knife4j made up for these deficiencies and gave Swagger more functions. Today we will talk about how to use it.

Introduction to knife4j

Knife4j is an enhanced UI implementation of springfox-swagger, which provides a simple and powerful interface documentation experience for Java developers when using Swagger. Knife4j completely follows the usage method in springfox-swagger and has enhanced functions on this basis. If you have used Swagger, you can seamlessly switch to knife4j.

Quick start

Next, we will introduce how to use knife4j in SpringBoot, just two steps!

• Increase the relevant dependencies of knife4j in pom.xml;

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

• Add a @EnableKnife4j annotation to Swagger2Config, which can enable the enhanced function of knife4j;

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

• Run our SpringBoot application and visit the API document address to view: http://localhost:8088/doc.html

 

Features

Next, let's compare Swagger and see what is the difference between using knife4j and it!

JSON function enhancement

I always use Swagger, but Swagger's JSON support has not been very good. JSON cannot be folded and is too long to see. When passing JSON format parameters, there is no parameter verification function. These pain points have been resolved on knife4j.

• The returned result set supports folding for easy viewing;

 

• The request parameter has JSON verification function.

 

Login authentication

knife4j also supports adding Token to the header for login authentication.

• First add the Token returned by login in the Authorize function;

 

• Afterwards, in each interface, you can see that the Token information has been carried in the request header.

 

Offline documents

knife4j supports exporting offline documents for easy sending to others and supports Markdown format.

• Directly select document management -> offline document function, and then choose to download Markdown;

 

• Let's check the exported Markdown offline document, which is still very detailed.

 

Global parameters

knife4j supports temporary setting of global parameters, and supports two types of query (form) and header (request header).

• For example, if we want to add a parameter appType to all request headers to distinguish whether it is an android or ios call, we can add it in the global parameters;

 

• When the interface is called at this time, the request header appType will be included.

 

Ignore parameter attributes

Sometimes the interface we create and modify will use the same object as the request parameter, but we don't need id when we create it, and we need id when we modify it. At this time, we can ignore the id attribute.

• For example, in the product creation interface here, the id, product quantity, and product comment number can be generated without passing the background interface. You can use the @ApiOperationSupport annotation provided by knife4j to ignore these attributes;

/**
 * 品牌管理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;
    }}

• At this time, when viewing the interface document, I found that these three attributes have disappeared, so that front-end development will not feel that you have defined useless parameters when viewing the interface document. Is it a very good function?

 

Reference

Official document: https://doc.xiaominfo.com/guide/

Project source address

https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-knife4j