Springboot整合knife4j生成文档

前言

在开发过程中，接口文档是很重要的内容，用于前端对接口的联调，也用于给其他方使用。但是手写相对比较麻烦。

当然也有swagger之类的，但是界面没有那么友好。

官网：

整合步骤

整合依赖

需要根据版本进行，具体可以参考文档

我这里是springboot 2.6.7的，因此使用 OpenAPI2即可

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

配置yaml文件

knife4j:
  enable: true
#  基础权限访问配置
  basic:
    enable: true
    # Basic认证用户名
    username: test
    # Basic认证密码
    password: 123
  openapi:
#    配置基础信息
    title: Knife4j官方文档
    description: "`我是测试`,**你知道吗**
    # aaa"
    email: xiaoymin@foxmail.com
    concat: 八一菜刀
    url: https://docs.xiaominfo.com
    version: v4.0
    license: Apache 2.0
    license-url: https://stackoverflow.com/
    terms-of-service-url: https://stackoverflow.com/
#    分组配置， 可用于扫描不同的包
    group:
      test1:
        group-name: 测试分组1
        api-rule: package
        api-rule-resources:
          - com.walker.knife4j.controller

具体的配置，可以查看配置类和文档

/*
 * Copyright 2017-2022 八一菜刀(xiaoymin@foxmail.com)
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */


package com.github.xiaoymin.knife4j.spring.configuration;

import com.github.xiaoymin.knife4j.core.model.MarkdownProperty;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

import java.util.List;

/***
 * Knife4j Basic Properties
 * @since  1.9.6
 * @author <a href="mailto:xiaoymin@foxmail.com">xiaoymin@foxmail.com</a> 
 * 2019/08/27 15:40
 */
@Component
@Data
@ConfigurationProperties(prefix = "knife4j")
public class Knife4jProperties {

    /**
     * Whether to enable knife4j enhanced mode
     */
    private boolean enable = false;
    /**
     * Basic Document OpenAPI information
     */
    private Knife4jInfoProperties openapi;
    /**
     * Enable default cross domain,default is false.
     */
    private boolean cors = false;

    /**
     * Enable HTTP Basic authentication,default is false.
     */
    private Knife4jHttpBasic basic;

    /**
     * Is it in the production environment? If yes, all documents cannot be accessed at present，default is false
     */
    private boolean production = false;

    /**
     * The Personalized configuration
     */
    private Knife4jSetting setting;

    /**
     * The group of Custom Markdown resources
     */
    private List<MarkdownProperty> documents;
}

编写测试接口

package com.walker.knife4j.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;

// 1、使用@Api注解，代表目录
@Api(value = "测试控制器", tags = "测试API")
@RestController
public class TestController {


    // 2、具体接口
    @ApiOperation("打招呼")
    @GetMapping("/hello")
    public String hello() {
        return "Hello ";
    }

}

其他相关注解可参考：

主要引用的是swagger的，knife4j是在swagger的基础上进行封装

启动项目、访问

注意：需要放开doc.html的白名单访问

访问路径：ip:port/doc.thml

访问后需要输入basic设置的账号密码

就可以看到我们的测试的类和方法了

可以根据注解进行请求参数、返回结果类的配置等

也可以直接使用调试功能对代码进行调试，具体便不再演示，可自行操作。