SpringBoot整合通用Swagger

整个工具的代码都在Gitee或者Github地址内

gitee：solomon-parent: 这个项目主要是总结了工作上遇到的问题以及学习一些框架用于整合例如:rabbitMq、reids、Mqtt、S3协议的文件服务器、mongodb、xxl-job、powerjob还有用Docker compose部署各类中间组件。如果大家有什么想要弄成通用组件的，可以给我留言，我可以研究下

github：https://github.com/ZeroNing/solomon-parent

需要引入的JAR包(版本根据自身要求使用，本教程用的版本均为最新)

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

1.新增配置类

@ConfigurationProperties("doc")
public class SwaggerProfile {
    
    /**
     * 文档名称
     */
    private String title;
    /**
     * 是否启用文档
     */
    private boolean enabled;

    private List<DocRequestParameter> globalRequestParameters;

    public static class DocRequestParameter implements Serializable {
        /**
         * 参数名
         */
        private String name;
        /**
         * 参数位置类型
         */
        private ParameterType in;
        /**
         * 参数描述说明
         */
        private String description;
        /**
         * 是否必填参数
         */
        private Boolean required;
        /**
         * 是否已弃用参数
         */
        private Boolean deprecated;
        /**
         * 是否隐藏参数
         */
        private Boolean hidden;

        public String getName() {
            return name;
        }

        public void setName(String name) {
            this.name = name;
        }

        public ParameterType getIn() {
            return in;
        }

        public void setIn(ParameterType in) {
            this.in = in;
        }

        public String getDescription() {
            return description;
        }

        public void setDescription(String description) {
            this.description = description;
        }

        public Boolean getRequired() {
            return required;
        }

        public void setRequired(Boolean required) {
            this.required = required;
        }

        public Boolean getDeprecated() {
            return deprecated;
        }

        public void setDeprecated(Boolean deprecated) {
            this.deprecated = deprecated;
        }

        public Boolean getHidden() {
            return hidden;
        }

        public void setHidden(Boolean hidden) {
            this.hidden = hidden;
        }
    }

    public List<DocRequestParameter> getGlobalRequestParameters() {
        return globalRequestParameters;
    }

    public void setGlobalRequestParameters(List<DocRequestParameter> globalRequestParameters) {
        this.globalRequestParameters = globalRequestParameters;
    }

    public String getTitle() {
        return title;
    }

    public void setTitle(String title) {
        this.title = title;
    }

    public boolean getEnabled() {
        return enabled;
    }

    public void setEnabled(boolean enabled) {
        this.enabled = enabled;
    }
}

2.获取git最新提交记录

<build>
    <plugins>
        <plugin>
            <groupId>pl.project13.maven</groupId>
            <artifactId>git-commit-id-plugin</artifactId>
            <version>2.1.5</version>
            <executions>
                <execution>
                    <id>get-the-git-infos</id>
                    <!-- 默认绑定阶段initialize -->
                    <phase>initialize</phase>
                    <goals>
                        <goal>revision</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <!--日期格式;默认值:dd.MM.yyyy '@' HH:mm:ss z;-->
                <dateFormat>yyyy-MM-dd_HH-mm-ss</dateFormat>
                <!--,构建过程中,是否打印详细信息;默认值:false;-->
                <verbose>true</verbose>
                <!-- ".git"文件路径;默认值:${project.basedir}/.git; ${project.basedir}：项目根目录，即包含pom.xml文件的目录-->
                <dotGitDirectory>${project.basedir}/../../../.git</dotGitDirectory>
                <!--若项目打包类型为pom,是否取消构建;默认值:true;-->
                <skipPoms>false</skipPoms>
                <!--是否生成"git.properties"文件;默认值:false;-->
                <generateGitPropertiesFile>true</generateGitPropertiesFile>
                <!--指定"git.properties"文件的存放路径(相对于${project.basedir}的一个路径);-->
                <generateGitPropertiesFilename>/src/main/resources/git.properties</generateGitPropertiesFilename>
                <!--".git"文件夹未找到时,构建是否失败;若设置true,则构建失败;若设置false,则跳过执行该目标;默认值:true;-->
                <failOnNoGitDirectory>true</failOnNoGitDirectory>

                <!--git描述配置,可选;由JGit提供实现;-->
                <gitDescribe>
                    <!--是否生成描述属性-->
                    <skip>false</skip>
                    <!--提交操作未发现tag时,仅打印提交操作ID,-->
                    <always>false</always>
                    <!--提交操作ID显式字符长度,最大值为:40;默认值:7; 0代表特殊意义;后面有解释;-->
                    <abbrev>7</abbrev>
                    <!--构建触发时,代码有修改时(即"dirty state"),添加指定后缀;默认值:"";-->
                    <dirty>-dirty</dirty>
                    <!--always print using the "tag-commits_from_tag-g_commit_id-maybe_dirty" format, even if "on" a tag.
                        The distance will always be 0 if you're "on" the tag.  -->
                    <forceLongFormat>false</forceLongFormat>
                </gitDescribe>
            </configuration>
        </plugin>
    </plugins>
</build>

3.新增Swagger配置类

@Configuration
@EnableSwagger2WebMvc
@EnableConfigurationProperties(value={SwaggerProfile.class,})
public class SwaggerConfig {

  private final SwaggerProfile profile;

  public SwaggerConfig(SwaggerProfile profile) {
      this.profile = profile;
  }

  @Bean
  @ConditionalOnMissingBean(Docket.class)
  public Docket createRestApi() {
    List<RequestParameter> requestParameters = new ArrayList<>();
    if(ObjectUtil.isNotEmpty(profile.getGlobalRequestParameters())){
      // 创建必要参数对象
      RequestParameterBuilder requestParameterBuilder = new RequestParameterBuilder();
      for(SwaggerProfile.DocRequestParameter requestParameter: profile.getGlobalRequestParameters()){
        requestParameters.add(requestParameterBuilder.name(requestParameter.getName())
                .in(requestParameter.getIn())
                .description(requestParameter.getDescription())
                .required(requestParameter.getRequired())
                .hidden(requestParameter.getHidden())
                .build());
      }
    }
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        //是否开启 (true 开启  false隐藏。生产环境建议隐藏)
        .enable(profile.getEnabled())
        .select()
        //扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
        .apis(RequestHandlerSelectors.any())
        //指定路径处理PathSelectors.any()代表所有的路径
        .paths(PathSelectors.any())
        .build().globalRequestParameters(requestParameters);
  }

  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
        //设置文档标题(API名称)
        .title(profile.getTitle())
        //版本号
        .version(getGitVersion())
        .build();
  }

  private String getGitVersion() {
    String version = "1.0.0";
    try {
      ClassLoader classLoader = getClass().getClassLoader();
      URL         resource    = classLoader.getResource("git.properties");
      if (resource != null) {
        Properties props = new Properties();
        props.load(resource.openStream());

        String abbrev= props.getProperty("git.commit.id.abbrev");
        String time=props.getProperty("git.build.time");
//        String user = props.getProperty("git.build.user.name");
        version = time + "-" + abbrev ;
      }
    } catch (Throwable e) {
      version = "1.0.0";
    }
    return version;
  }
}

4.测试

在application.yml加入一下配置，测试用例都是用SpringBootDemo测试用的

i18n:
  all-locale: zh,en
  language: zh
  path: i18n/messages
server:
  port: 8001
doc:
  title: rabbitmq测试用例
  enabled: true
  globalRequestParameters:
    - name: token
      in: HEADER
      description: 用户认证令牌
      required: true
      deprecated: false
      hidden: false
spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher
  jmx:
    enabled: true
  servlet:
    multipart:
      max-file-size: 20MB
      max-request-size: 20MB