Knife4j框架的使用

为什么使用Knife4j框架

在工作当中的主流做法就是前后端分离的开发模式，所谓的这种模式就是分工作业各干各的。分离好处：项目是分离的，导致人员也是分离的，多人协作些项目，之后拼在一起。项目上线部署也可以分离，也就是前后端各放到一个服务器。这种模式分为两拨人，前端人员不是很清楚后端做了些什么，为了最后项目的整合前端必须要知道，以什么方式访问向后端发起请求，发送什么请求参数，响应回来什么结果。为了解决这个问题，正确的做法就是使用API文档工具，它可以基于所写的代码实时的生成API文档。降低前后端的沟通成本。

添加依赖

这里依赖版本2.0.9，它只支持2.5系列版本的SpringBoot

    <!-- Knife4j Spring Boot：在线API文档 -->
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
        <version>2.0.9</version>
    </dependency>

 添加配置(主要配置Controller包路径)

/**
 * Knife4j配置类
 */
@Slf4j
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {
    //【重要】指定Controller包路径
    private String basePackage = "do.xfk.tea.admin.server";
    //主机名
    private String host = "http://java.xfk.do";
    //标题
    private String title = "学茶商城后台管理平台在线API文档";
    //简介
    private String description = "学茶商城后台管理平台在线API文档";
    //服务条款URL
    private String termsOfServiceUrl = "http://www.apache.org/licenses/LICENSE-2.0";
    //联系人
    private String contactName = "Java教学研发部";
    //联系网址
    private String contactUrl = "http://java.xxx.cn";
    // 联系邮箱
    private String contactEmail = "12346@qq.com";
    //版本号
    private String version = "1.0";

    @Autowired
    private OpenApiExtensionResolver openApiExtensionResolver;

    public Knife4jConfiguration() {
        log.debug("创建配置类对象：Knife4jConfiguration");
    }

    @Bean
    public Docket docket() {
        String groupName = "1.0.0";
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .host(host)
                .apiInfo(apiInfo())
                .groupName(groupName)
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any())
                .build()
                .extensions(openApiExtensionResolver.buildExtensions(groupName));
        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .termsOfServiceUrl(termsOfServiceUrl)
                .contact(new Contact(contactName, contactUrl, contactEmail))
                .version(version)
                .build();
    }
}

 解决配置类报错

解决方案：（在配置文件中）

# Knife4j配置
knife4j:
  # 开启增强模式
  enable: true

访问

访问API文档地址：http://localhost:9080/doc.html

9080端口号是自己在服务器端配置的端口号。

运行效果

​

左侧请求的显示是根据编写controller类中方法的请求方式，若不指定请求方式，默认7种请求方式全部显示在API左侧导航栏。

结合注解进行说明配置

@Api(tags = "2.2. 内容管理-标签管理")：配置API文档侧栏子菜单项父级的名称，这里的数字是为了后期多个controller类进行排序。

@ApiOperation("新增标签类别")：配置API中显示的方法名。这里加数字进行排序是不生效的。

@ApiOperationSupport(order = 100)：根据order的值对API中方法的显示先后顺序进行排序。建议按照增删改查进行排序，为了穿插排序，order值尽量设置大一点。

这里请求方法参数前没有加@RequestBody的原因，它会导致API文档可读性不好，以及测试输入对应参数值不直观。

@Slf4j
@RestController
@RequestMapping("/content/tags")
@Api(tags = "2.2. 内容管理-标签管理")
public class TagController {

    @Autowired
    private ITagService tagService;

    @ApiOperation("新增标签类别")
    @ApiOperationSupport(order = 100)
    @PostMapping("/type/add-new")
    public JsonResult addNew(TagTypeAddNewParam tagTypeAddNewParam){
        log.debug("开始处理【新增标签类别】的请求,参数:{}",tagTypeAddNewParam);
        tagService.addNew(tagTypeAddNewParam);
        return JsonResult.ok();
    }
}

配置注解调整API显示效果：

 显示在API中请求参数的配置

@ApiModelProperty(value = "是否启用，1=启用，0=未启用", required = true,example = "1")：用来配置API中参数说明；required = true是对参数是否必须进行设置，true则为必须提交，根据实际需求进行设置，加了之后在API文档中调试时参数必须填写；example配置实例值，使使用API文档人员更容易理解；如果注解参数为1时，value=可以省略不写。

/**
 * 新增标签类型的参数类
 */
@Data
public class TagTypeAddNewParam implements Serializable {
    /**
     * 标签类别名称
     */
    @NotNull(message = "请提交标签类别名称")
    @Pattern(regexp = "^[a-zA-Z\\u4e00-\\u9fa5]{2,10}$",
            message = "标签类别必须是2~10长度的字符组成，且不允许使用标点符号")
    @ApiModelProperty(value = "标签类别名称", required = true)
    private String name;
    /**
     * 是否启用，1=启用，0=未启用
     */
    @NotNull(message = "请提交标签类别是否启用")
    @Range(max = 1, message = "是否启用的值必须是0或1")
    @ApiModelProperty(value = "是否启用，1=启用，0=未启用", required = true, example = "1")
    private Integer enable;
    /**
     * 排序序号
     */
    @NotNull(message = "请提交标签类别排序序号")
    @Range(max = 99, message = "排序序号必须是0~99之间的值")
    @ApiModelProperty(value = "排序序号", required = true)
    private Integer sort;

}