springboot custom starter component - integrated swagger3 documentation

SpringBoot automatic assembly principle

The core of springboot is automatic assembly, so why can jar be used out of the box?
By viewing the source code, you can find that when the project is started, you will go to META-INF/spring.factories to obtain the fully qualified name of the configuration class that needs automatic assembly, and then compare it with the resources introduced in pom to finally judge whether it meets the assembly conditions.

Customize your own Starter to provide swagger online document function

The official naming format of starter is spring boot starter - {XXXX}, such as spring boot starter ActiveMQ
For the third party, our own naming format is {XXXX} - spring boot starter. For example, mybatis spring boot starter.
We named it swagger3 spring boot starter this time, which shows our professional level

1. Introduce dependency

    <!-- custom springboot This dependency must be introduced as an entry -->

    <!-- Automatic prompt function when reading configuration file -->

    <!--introduce swagger3 -->

    <!--Integration enhancement document knife4j-->

2. Write configuration file mapping class

The provided component parameters are read from other project configuration files to realize the configurability of parameters

package com.xwzhou.config;

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

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

   * Document name
  private String title;
   * Author name
  private String name;
   * url
  private String url;
   * email
  private String email;
   * edition
  private String version;
   * brief introduction
  private String description;

//Omit the get/set method and pay attention to your own supplement

3. Write swagger3 auto configuration class

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;

 * @author xwzhou swagger3 to configure
//Indicates that the current automatic configuration will be executed only when Swagger3In is injected
//Make the @ ConfigurationProperties annotation in Swagger3Properties.class effective
//Annotation and @ Bean annotation are used to generate beans: This is the same as JavaConfig. The purpose is to generate beans and put them into containers.
//Enhanced document knife4j
public class Swagger3Config {

  private Swagger3Properties properties;

   * swagger3 Configuration file for
  public Docket createRestApi() {
    return new Docket(DocumentationType.OAS_30)

   * Build the detailed function of the api document. Note which annotation refers to here
  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
        .contact(new Contact(properties.getName(), properties.getUrl(), properties.getEmail()))


Swagger3In class is an empty class, which means that the current automatic configuration will be executed only when Swagger3In is injected

package com.xwzhou.config;

public class Swagger3In {


4. Define the annotation class to make the starter effective

  • Passive entry into force
    Load our starter through the SPI mechanism of SpringBoot. We need to create a new spring.factories file under META-INF. the key is org.springframework.boot.autoconfigure.EnableAutoConfiguration, and the value is the fully qualified name of our swagger3 configuration class (remember to remove the spaces before and after, otherwise it will not take effect).
  • Active entry into force
    When the starter component is integrated into our Spring Boot application, we need to actively declare that the starter is enabled before it takes effect. We can customize an @ EnableSwagger3 annotation, and then introduce the automatic configuration class through the Import annotation.
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;

public @interface EnableSwagger3 {


5. Package jar

exec is very important here, and it is also a place where many materials do not describe clearly


Just use the mvn install command

The first jar is our component package

Other project reuse components

  1. Project import dependent components
  • You can upload components to the company's private server and let colleagues introduce jar pom (the first one is recommended)
  • Directly give the jar to your colleagues and put it in your local warehouse
  1. configuration file
# swagger document switch off
      enabled: false
  title: zhoudawei-project API Interface documentation
  name: xwzhou author
  url: www.xxxx.com
  email: xxxxxx@qq.com
  version: 1.0 edition
  description: API Document introduction

# knife4j enhanced document opening (production environment to be closed)
# Access address: http://localhost:8080/doc.html
  enable: true
  1. Introduction of annotations to enable automatic assembly
  2. Start project validation
    Access address: http://localhost:8080/doc.html


If you have any questions, please leave a message for discussion. Leave a message and return it!
If you think the article is good, your forwarding, sharing, appreciation, praise and comments are my greatest encouragement.
Thank you for your reading. Welcome and thank you for your attention.

Tags: Java Spring Spring Boot

Posted on Thu, 21 Oct 2021 01:34:46 -0400 by blakogre