Knife4j Gateway使用详解

Knife4j Gateway是一款开源、免费的API文档管理工具，基于SpringBoot2.x、Swagger2、Bootstrap、Vue.js等技术实现，提供了前后端完全分离的方式来展示API文档，使开发人员能够轻松地创建、维护和分享API文档。本文将从多个方面对Knife4j Gateway进行详细的阐述。

一、快速上手

1、引入依赖


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

2、在配置文件中进行配置


# Knife4j配置信息
knife4j:
  # Swagger-API文档基础信息配置
  api-docs:
    groupName: xxx项目API文档
    apiBasePackage: 导入项目中需要生成文档的接口基础包名
    title: xxx API接口文档
    description: xxx接口文档描述信息
    contact:
      name: xxxx
      email: xxxx
      url: "xxx"
    version: 1.0.0
    license:
      name: xxxx
      url: xxxx
    termsOfServiceUrl: xxxx
    host: xxxx
  # GatewayAPI配置信息
  gateway:
    globalLatencyTiming: true

3、创建接口文档类


@RestController
@Api(tags = "测试接口管理")
@RequestMapping("/test")
public class TestController {

    @ApiOperation(value = "测试API", notes = "测试API")
    @ApiResponses({@ApiResponse(code = 200, message = "操作成功", response = String.class)})
    @GetMapping(value = "/echo/{string}", produces = MediaType.APPLICATION_JSON_VALUE)
    public String echo(@PathVariable String string) {
        return "echo:" + string;
    }

}

4、启动项目，访问http://localhost:port/doc.html即可查看API文档页面。

二、功能详细介绍

1、基本信息配置

在Knife4j Gateway中，可以通过配置文件进行基本信息的配置，或者通过Java注解进行详细的配置。


@Api(tags = {"用户信息管理"})
@ApiInfo(value = "用户信息管理", description = "用户信息管理API接口文档")
@RestController
@RequestMapping(value = "/user")
public class UserController {

    @ApiOperation(value = "根据ID获取用户信息", notes = "获取指定ID的用户信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        return userService.getUserById(id);
    }

}

2、接口说明

在Knife4j Gateway中，使用@Api注解来标记接口说明信息。


@Api(tags = {"用户信息管理"})
public interface UserService {

    @ApiOperation(value = "获取所有用户信息", notes = "获取所有用户信息")
    List listAllUser();

}

3、参数说明

在Knife4j Gateway中，使用@ApiImplicitParam注解来标记参数说明信息。


@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
@GetMapping("/{id}")
public User getUserById(@PathVariable Long id) {
    return userService.getUserById(id);
}

4、返回值说明

在Knife4j Gateway中，使用@ApiResponse注解来标记返回值说明信息。


@ApiResponses({@ApiResponse(code = 200, message = "操作成功", response = String.class)})
@GetMapping(value = "/hello")
public String sayHello() {
    return "Hello World!";
}

5、分组管理

在Knife4j Gateway中，可以通过分组管理来区分不同的API接口，方便API接口的管理和查找。


@Api(tags = {"用户信息管理"})
public interface UserService {

    @ApiOperation(value = "获取所有用户信息", notes = "获取所有用户信息")
    List listAllUser();

}

@Api(tags = {"订单信息管理"})
public interface OrderService {

    @ApiOperation(value = "获取所有订单信息", notes = "获取所有订单信息")
    List listAllOrder();

}

三、常用扩展

1、集成Swagger-Bootstrap-UI

Swagger-Bootstrap-UI是一款基于Swagger2的API文档UI增强工具，可以帮助API文档页面展示的更加美观和易于使用。通过在Knife4j Gateway中引入Swagger-Bootstrap-UI，可以让API文档页面拥有更加丰富的功能。

引入Swagger-Bootstrap-UI的依赖：


<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.4</version>
</dependency>

在配置文件中启用Swagger-Bootstrap-UI：


# Swagger-Bootstrap-UI配置信息
swagger:
  base-package: 扫描项目中需要生成文档的接口基础包名
  contact:
    name: 某某公司
  title: 项目名称 - API接口文档
  description: 项目描述信息
  enable: true
  version: 1.0.0
  termsOfServiceUrl: http://xxxx
  authorization:
    name: Authorization
    description: 在请求头中添加Token信息，格式为"Bearer token"

2、API文档访问控制

在一些敏感的项目中，需要对API文档的访问进行控制，防止未授权的人员访问API文档。Knife4j Gateway提供了访问控制的方式，使用Spring Security进行安全控制。

添加Spring Security的依赖：


<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

配置Spring Security：


@Configuration
@EnableWebSecurity
public class WebSecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
                .authorizeRequests()
                .antMatchers("/doc.html", "/webjars/**", "/v2/api-docs", "/swagger-resources/**")
                .permitAll()
                .anyRequest()
                .authenticated()
                .and()
                .formLogin()
                .loginPage("/login.html")
                .permitAll()
                .and()
                .logout()
                .permitAll();
    }

    @Override
    public void configure(WebSecurity web) throws Exception {
        web.ignoring().antMatchers("/css/**", "/js/**", "/webjars/**");
    }
}

3、接口文档自定义UI

在Knife4j Gateway中，默认使用了Bootstrap-Vue作为UI框架，但是开发人员可以根据自己的需求进行UI的自定义，以便更好的满足业务需求。

在resources/templates目录下创建自定义的HTML模板，使用FreeMarker或Thymeleaf等模板引擎来渲染页面，然后在配置文件中进行UI的配置即可。


# UI配置信息
knife4j:
  ui:
    isDefault: false # 是否使用默认UI
    url: /doc.html # 访问API文档的URL
    title: 项目名称API接口文档 # 页面标题
    logo: /static/images/logo.png # Logo图片地址
    tagsSorter: alpha # 标签排序方式：alpha/alphabetical/alphaDesc
    operationsSorter: method # 操作排序方式：method/methodDesc/path/pathDesc
    disableFilter: false # 是否禁用过滤功能
    enableSwaggerBootstrapUi: true # 是否启用Swagger-Bootstrap-UI
    apiDocsUrl: /v2/api-docs # 获取API文档信息的URL
    footer:
      name: xxx公司 # 版权信息
      url: http://xxxx # 链接地址

四、常见问题

1、如何在Knife4j Gateway中使用全局异常处理？

Knife4j Gateway默认使用SpringBoot的全局异常处理，但是在一些特殊的业务场景中，可能需要自定义全局异常处理。可以通过@ControllerAdvice注解来实现的全局异常处理。


@ControllerAdvice
public class GlobalExceptionHandler {

    /**
     * 处理异常：NullPointerException
     *
     * @param e NullPointerException异常
     * @return 错误信息
     */
    @ExceptionHandler(value = {NullPointerException.class})
    public ResponseEntity handleNullPointerExceptionException(Exception e) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("系统繁忙！");
    }

}

2、如何为Knife4j Gateway中的接口设置访问限制？

为了保护系统的安全和稳定，可能需要为Knife4j Gateway中的接口设置访问限制。可以通过使用Spring Security等安全框架来为接口设置访问限制。

3、如何将Knife4j Gateway中的API文档集成到SwaggerHub中？

可以使用SwaggerHub提供的导入功能，将Knife4j Gateway中的API文档导入到SwaggerHub中进行管理。

在SwaggerHub中，选择“APIs”菜单，然后在“New API”下拉菜单中选择“Import API”，在弹出的窗口中选择“Import from Remote URL”，输入Knife4j Gateway中API文档的URL，然后点击“Import API”按钮完成导入。

五、总结

通过本文的介绍，不难看出Knife4j Gateway具有许多丰富的功能和优秀的易用性，对于开发人员来说是一款非常实用和优秀的API文档管理工具。使用Knife4j Gateway可以让开发人员轻松地创建、维护和分享API文档，从而提高项目的效率和可维护性。

原创文章，作者：VFXWN，如若转载，请注明出处：https://www.506064.com/n/334780.html