关于knife4j工具聚合api文档的使用

1 knife4j工具的介绍
- - 简单案例
  - - 1 导入Knife4j依赖
    - 2 添加配置文件
    - 3 添加控制器
    - 4 查看文档
2 knife4j工具的使用
- - 聚合微服务文档案列
  - - 文档服务
    - 业务服务1
    - 业务服务2
    - 查看文档

在目前微服务项目中, 通常使用swagger作为在线文档交流使用,但各个微服务的文档都各自管理, 比较分散, 且没有导出离线文档等功能,而knife4j工具可以解决上述问题

1 knife4j工具的介绍

knife4j是2017年开源的一款增强swagger的工具, 主要是为Java开发框架集成Swagger生成Api文档的增强解决方案(主要是Java的Spring MVC, Spring Boot, Spring Cloud等非Java语言)，前身是swagger-bootstrap-ui,取名knife4j是作者希望她能像一把匕首一样小巧,轻量,并且功能强悍.

简单案例

knife4j是增强swagger的工具,所以使用方式,配置等和使用swagger类似.

前提: 准备一个可运行的SpringBoot环境.

1 导入Knife4j依赖


    com.github.xiaoymin
    knife4j-spring-boot-starter
    2.0.7

2 添加配置文件

@Configuration
@EnableSwagger2WebMvc
public class Knife4jDocConfiguration {

    
    @Bean
    @ConditionalOnMissingBean
    public Docket apiDocket2() {
        // 默认组名, 文档更具组名查询,不同组名不能聚合
        String groupName = "default";
        return new Docket(documentationType.SWAGGER_2)
                // 文档信息
                .apiInfo(getApiInfo())
                // 组名
                .groupName(groupName)
                .select()
                // 指定Controller扫描包路径(如下面第一个apis方法)     因Controller类上要添加Api注解, 所以可通过指定类上注解
                // .apis(RequestHandlerSelectors.basePackage("com.github.xiaoymin.knife4j.controller"))
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build()
    }


    
    private ApiInfo getApiInfo() {
        // 用ApiInfoBuilder进行定制
        return new ApiInfoBuilder()
                // 设置标题
                .title(appName + "服务接口文档")
                // 描述
                .description("接口的相关文档")
                // 作者信息
                .contact(new Contact("李白", "www.libai.com", "libai@qq.com"))
                // 版本
                .version("1.0")
                .build();
    }

}

3 添加控制器

@RestController
@Slf4j
@Api(value = "AConController", tags = "消费者控制器")
public class AConController {

    @Autowired
    private ProviderFeign providerFeign;

    @GetMapping("/consumer")
    public String list() {
        String info = "我是consumerA,8081    ";
        log.info(info);
        String result = providerFeign.list();
        return JSON.toJSONString(info + result);
    }

}

4 查看文档

访问文档地址http://localhost:8080/doc.html

2 knife4j工具的使用聚合微服务文档案列

准备服务: 一个文档服务,两个业务服务,nacos注册配置中心

文档服务

1 准备一个可运行的SpringBoot服务

2 添加knife4j依赖

    
      com.github.xiaoymin
      knife4j-aggregation-spring-boot-starter
      2.0.9

3 application.yml文件添加配置

knife4j:
  # 开启聚合  
  enableAggregation: true
  nacos:
    enable: true
    serviceUrl: http://localhost:8848/nacos
    routeAuth:
      enable: true
      password: nacos
      username: nacos
    routes:
      - name: provider-a服务
        serviceName: provider-a
        location: /v2/api-docs?group=default
        servicePath: /
      - name: consumer-a服务
        serviceName: consumer-a
        location: /v2/api-docs?group=default
        servicePath: /

业务服务1

1 准备一个可运行的SpringBoot服务

2 添加配置类

@Configuration
@EnableSwagger2WebMvc
public class Knife4jDocConfiguration {

    
    @Value("${spring.application.name:应用}")
    private String appName;

    
    @Autowired(required = false)
    private OpenApiExtensionResolver openApiExtensionResolver;

    
    @Bean
    @ConditionalOnMissingBean
    public Docket apiDocket2() {
        // 默认组名, 文档更具组名查询,不同组名不能聚合
        String groupName = "default";
        return new Docket(documentationType.SWAGGER_2)
                // 文档信息
                .apiInfo(getApiInfo())
                // 组名
                .groupName(groupName)
                .select()
                // 指定Controller扫描包路径(如下面第一个apis方法)     因Controller类上要添加Api注解, 所以可通过指定类上注解
                // .apis(RequestHandlerSelectors.basePackage("com.github.xiaoymin.knife4j.controller"))
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build()
                // 赋予插件体系
                .extensions(getExtensions(groupName));
    }


    
    private ApiInfo getApiInfo() {
        // 用ApiInfoBuilder进行定制
        return new ApiInfoBuilder()
                // 设置标题
                .title(appName + "服务接口文档")
                // 描述
                .description("接口的相关文档")
                // 作者信息
                .contact(new Contact("李白", "www.libai.com", "libai@qq.com"))
                // 版本
                .version("1.0")
                .build();
    }

    
    private List getExtensions(String groupName) {
        return null != openApiExtensionResolver ? openApiExtensionResolver
                .buildExtensions(groupName) : new ArrayList<>();
    }
}

3 可在后台配置,添加到自动装配 (增强特性时使用)

在resources文件夹下增加meta-INF文件夹,spring.factories文件

org.springframework.boot.autoconfigure.EnableAutoConfiguration=
com.cf.config.Knife4jDocConfiguration

ps: 如果有多个自动配置注入使用,分隔

org.springframework.boot.autoconfigure.EnableAutoConfiguration=
com.cf.config.Knife4jDocConfiguration,
com.cf.config.Configuration

4 添加控制器

@RestController
@Slf4j
@Api(value = "AConController", tags = "消费者控制器")
public class AConController {

    @Autowired
    private ProviderFeign providerFeign;

    @GetMapping("/consumer")
    public String list() {
        String info = "我是consumerA,8081    ";
        log.info(info);
        String result = providerFeign.list();
        return JSON.toJSONString(info + result);
    }

}

业务服务2

基本配置和服务一相同.

查看文档

1 启动本地nacos ,再依次启动文档服务knife4j-doc服务 , provider-a服务 , consumer-a服务

2 启动本地nacos服务,查看服务列表,发现存在三个服务

knife4j-doc服务
provider-a服务
consumer-a服务

3 查看文档服务knife4j-doc的文档

http://localhost:8000/doc.html

发现provider-a和consumer-a服务的Controller文档已经被聚合出来,可以查看和测试了.

参考资料:

https://doc.xiaominfo.com/knife4j/documentation/enhance.html

https://blog.csdn.net/weixin_47560078/article/details/116560060

关于knife4j工具聚合api文档的使用

Java相关栏目本月热门文章