knife4j-swagger接入

knife4j-swagger接入

GitHub地址：https://github.com/xiaoymin/swagger-bootstrap-ui

官网：https://xiaoym.gitee.io/knife4j/documentation/

一、接入项目

1.1、公共配置

将swagger公共使用的东西拆分到nm-common-core模块中，避免每个模块都需要些重复的东西。

• 引入依赖

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

只需要引入这个依赖即可，springfox-swagger2这些依赖都包含在内了，不需要再次引入。

• 定义自定义配置对象

package com.centre.common.model;

import lombok.Builder;
import lombok.Data;
import lombok.EqualsAndHashCode;

/**
 * Swagger自定义配置
 * Created by macro on 2020/7/16.
 */
@Data
@EqualsAndHashCode(callSuper = false)
@Builder
public class SwaggerDO {
    /**
     * API文档生成基础路径
     */
    private String apiBasePackage;
    /**
     * 是否要启用登录认证
     */
    private boolean enableSecurity;
    /**
     * 文档标题
     */
    private String title;
    /**
     * 文档描述
     */
    private String description;
    /**
     * 文档版本
     */
    private String version;
    /**
     * 文档联系人姓名
     */
    private String contactName;
    /**
     * 文档联系人网址
     */
    private String contactUrl;
    /**
     * 文档联系人邮箱
     */
    private String contactEmail;
}

这个配置可以写也可以不用写，使用默认呗。

• Swagger基础配置

• 定义自定义配置类

这个类用于是否使用swagger，swagger我们只是在开发环境下使用，如果是线上环境是不需要使用的，如果想swagger应用到线上环境是非常危险。所以这里的定义是如果不做任何配置的情况下，默认是关闭swagger的，为了安全着想。

1.2、在需要使用的模块下配置

创建配置文件

package com.user.auth.config;

import com.centre.common.config.BaseSwaggerConfig;
import com.centre.common.model.SwaggerDO;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger API文档相关配置
 * @author: stars
 * @data: 2020年 11月 27日 11:38
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
@ConditionalOnProperty(prefix = "nm.swagger",value = {"enable"},havingValue = "true")
public class SwaggerConfig extends BaseSwaggerConfig {

    @Override
    public SwaggerDO swaggerProperties() {
        return SwaggerDO.builder()
                .apiBasePackage("com.user.auth.controller")
                .title("用户管理系统")
                .description("用户相关接口文档")
                .contactName("stars")
                .version("1.0")
                .enableSecurity(false)
                .build();
    }
}

注意：apiBasePackage这里是API生成路径，需要指定前端控制器的包路径，否则不知道前端控制器在哪个地方。

二、使用介绍

@ApiOperation

当前接口的名称

@ApiOperation("添加品牌")
// 或者
@ApiOperation(value = "添加品牌")

@ApiOperationSupport

需要过滤掉的参数

过滤掉不用显示的参数，如果接口参数接收一个对象，但是这个对象里面可能存在一些当前接口不需要的参数，就可以使用这个注解过滤掉。

@ApiModelProperty

这个参数一般都是使用在对象上面，指定这个对象的描述和是否必须。如果普通对象，只需要指定描述就可以了，如果这个对象是作为参数使用，那么可以指定描述和当前参数是否必须。

@Api(tags = "代码生成")

使用在类明上

界面介绍