springboot自定义starter组件-集成swagger3文档

springboot的核心就是自动装配，那么为什么引入jar，就能开箱即用？
通过查看源码可以发现项目启动，会去找meta-INF/spring.factories，来获取需要自动装配的配置类的全限定名，再跟pom里引入的资源对比，最终判断是否符合装配条件。

官方的 starter 的命名格式为 spring-boot-starter-{xxxx} 比如spring-boot-starter-activemq
第三方我们自己的命名格式为 {xxxx}-spring-boot-starter。比如mybatis-spring-boot-starter。
我们这次就命名为swagger3-springboot-starter，显示出我们专业的水准

    
    
      org.springframework.boot
      spring-boot-autoconfigure
    

    
    
      org.springframework.boot
      spring-boot-configuration-processor
      true
    

    
    
      io.springfox
      springfox-boot-starter
      3.0.0
    

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

提供的组件参数从其他项目工程配置文件里读取，实现参数的可配置

package com.xwzhou.config;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "springfox")
public class Swagger3Properties {

  
  private String title;
  
  private String name;
  
  private String url;
  
  private String email;
  
  private String version;
  
  private String description;

//省略了get/set方法，注意自己补充
  
}

package com.xwzhou.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import io.swagger.v3.oas.annotations.Operation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.autoconfigure.condition.ConditionalOnBean;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.documentationType;
import springfox.documentation.spring.web.plugins.Docket;



//表示在注入Swagger3In情况下才会执行当前自动配置
@ConditionalOnBean(Swagger3In.class)
//使Swagger3Properties.class中的@ConfigurationProperties注解生效
@EnableConfigurationProperties(Swagger3Properties.class)
//注解配合@Bean注解来生成Bean：这与JavaConfig方式无异，目的是生成Bean并放入容器。
@Configuration
//增强文档knife4j
@EnableKnife4j
@EnableOpenApi
public class Swagger3Config {

  @Autowired
  private Swagger3Properties properties;

  
  @Bean
  public Docket createRestApi() {
    return new Docket(documentationType.OAS_30)
        .apiInfo(apiInfo())
        .select()
        .apis(RequestHandlerSelectors.withMethodAnnotation(Operation.class))
        .paths(PathSelectors.any())
        .build();
  }

  
  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
        .title(properties.getTitle())
        .contact(new Contact(properties.getName(), properties.getUrl(), properties.getEmail()))
        .version(properties.getVersion())
        .description(properties.getDescription())
        .build();
  }


}

Swagger3In类就是个空类，表示在注入Swagger3In情况下才会执行当前自动配置

package com.xwzhou.config;

public class Swagger3In {

}

• 被动生效
  通过SpringBoot的SPI的机制来去加载我们的starter。我们需要在meta-INF下新建一个spring.factories文件key为org.springframework.boot.autoconfigure.EnableAutoConfiguration， value是我们的swagger3配置类全限定名（记得去除前后的空格，否则会不生效）。
  org.springframework.boot.autoconfigure.EnableAutoConfiguration=com.xwzhou.config.Swagger3Config
  
• 主动生效
  在starter组件集成到我们的Spring Boot应用时需要主动声明启用该starter才生效，通过自定义一个@EnableSwagger3注解然后在把自动配置类通过import注解引入进来。

package com.xwzhou.config;

import java.lang.annotation.documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import org.springframework.context.annotation.import;

@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@documented
@import({Swagger3In.class})
public @interface EnableSwagger3 {

}

exec 这里很重要，也是很多资料没有描述清楚的地方

    
      
        org.springframework.boot
        spring-boot-maven-plugin
        
          exec
        
      
    
  

直接通过mvn install命令就可以了

第一个jar就是我们的组件包了

1. 项目引入依赖组件

• 可以把组件上传到公司的私服里，让同事引入jar pom即可（推荐第一种）
• 直接把jar给同事，放到自己的本地仓库

      com.xwzhou
      swagger3-springboot-starter
      0.0.1
    

2. 配置文件

# swagger 文档开关关闭
springfox:
  documentation:
    swagger-ui:
      enabled: false
  title: zhoudawei-project API接口文档
  name: xwzhou作者
  url: www.xxxx.com
  email: xxxxxx@qq.com
  version: 1.0 版本
  description: API文档简介


# knife4j增强型文档开启（生产环境要关闭）
# 访问地址：http://localhost:8080/doc.html
knife4j:
  enable: true

3. 引入注解开启自动装配
   
4. 启动项目验证
   访问地址：http://localhost:8080/doc.html
   

有问题请留言讨论，留言必回！
如果你觉得文章还不错，你的转发、分享、赞赏、点赞、留言就是对我最大的鼓励。
感谢您的阅读,十分欢迎并感谢您的关注。