编写自己的starter项目（battcn-starter-swagger）

Posted 2020-11-01 受伤滴小萝卜

自定义 starter 项目，方便其他地方调用，类似 spring.datasource.url 这种，本次以自己封装的 battcn-starter-swagger 为案例

创建一个Maven工程 battcn-starter-swagger

- pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.battcn</groupId>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.5.4.RELEASE</version>
    </parent>
    <artifactId>battcn-starter-swagger</artifactId>
    <name>battcn-starter-swagger</name>
    <url>http://blog.battcn.com</url>
    <description>基于SpringBoot1.5.4包装的Swagger只要依赖该JAR包即可做到自动装配</description>
    <version>1.0.1</version>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <java.version>1.8</java.version>
        <springfox.version>2.6.1</springfox.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox.version}</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
            <optional>true</optional>
        </dependency>
    </dependencies>

    <!--配置maven阿里云仓库开始,不用去改maven的setting -->
    <repositories>
        <repository>
            <id>public</id>
            <name>local private nexus</name>
            <url>http://maven.aliyun.com/nexus/content/groups/public/</url>
            <releases>
                <enabled>true</enabled>
            </releases>
        </repository>
    </repositories>
    <pluginRepositories>
        <pluginRepository>
            <id>public</id>
            <name>local private nexus</name>
            <url>http://maven.aliyun.com/nexus/content/groups/public/</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </pluginRepository>
    </pluginRepositories>
    <!--配置maven阿里云结束 -->
</project>

- SwaggerAutoConfiguration

定义我们的 SwaggerAutoConfiguration 自动装配类

package com.battcn.framework.swagger;

import java.time.LocalDate;
import java.util.ArrayList;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestMethod;
import com.battcn.framework.swagger.properties.ApiInfoProperties;
import com.battcn.framework.swagger.properties.DocketProperties;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * 自动装配类
 * @author Levin
 * @Q群：391619659
 */
@Configuration
@EnableConfigurationProperties(value = { SwaggerProperties.class })
@ConditionalOnProperty(name = "swagger.enable")
@EnableSwagger2
public class SwaggerAutoConfiguration {

    @Autowired
    SwaggerProperties properties;

    @Bean
    public Docket petApi() {
        DocketProperties docket = properties.getDocket();
        List<ResponseMessage> messages = new ArrayList<>();
        ResponseMessage message1 = new ResponseMessageBuilder().code(200).message("操作成功")
                .responseModel(new ModelRef("操作成功")).build();
        ResponseMessage message2 = new ResponseMessageBuilder().code(400).message("非法请求")
                .responseModel(new ModelRef("非法请求")).build();
        ResponseMessage message3 = new ResponseMessageBuilder().code(501).message("如请求路径拼写不正确")
                .responseModel(new ModelRef("如请求路径拼写不正确")).build();
        ResponseMessage message4 = new ResponseMessageBuilder().code(502).message("服务器过载引起的错误")
                .responseModel(new ModelRef("服务器过载引起的错误")).build();
        messages.add(message1);
        messages.add(message2);
        messages.add(message3);
        messages.add(message4);
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName(docket.getGroupName()).select()
                .apis(RequestHandlerSelectors.basePackage(docket.getBasePackage())).paths(PathSelectors.any()).build()
                .pathMapping("/").directModelSubstitute(LocalDate.class, String.class)
                .genericModelSubstitutes(ResponseEntity.class).useDefaultResponseMessages(false)
                .globalResponseMessage(RequestMethod.POST, messages);
    }

    private ApiInfo apiInfo() {
        ApiInfoProperties apiInfo = properties.getApiInfo();
        com.battcn.framework.swagger.properties.Contact contact = apiInfo.getContact();
        return new ApiInfoBuilder().title(apiInfo.getTitle()).description(apiInfo.getDescription())
                .termsOfServiceUrl(apiInfo.getTermsOfServiceUrl())
                .contact(new Contact(contact.getName(), contact.getUrl(), contact.getEmail()))
                .version(apiInfo.getVersion()).license(apiInfo.getLicense()).licenseUrl(apiInfo.getLicenseUrl())
                .build();
    }
}

- SwaggerProperties

这一步就是定义我们的 Properties 对象，目的就是可以被IDEA正确识别，然后可以依赖注入

package com.battcn.framework.swagger;

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

import com.battcn.framework.swagger.properties.ApiInfoProperties;
import com.battcn.framework.swagger.properties.DocketProperties;

@ConfigurationProperties(prefix = "swagger")
public class SwaggerProperties implements java.io.Serializable {

    private static final long serialVersionUID = 8471755917762607584L;
    private Boolean enable;
    private ApiInfoProperties apiInfo;
    private DocketProperties docket;

    public ApiInfoProperties getApiInfo() {
        return apiInfo;
    }

    public void setApiInfo(ApiInfoProperties apiInfo) {
        this.apiInfo = apiInfo;
    }

    public DocketProperties getDocket() {
        return docket;
    }

    public void setDocket(DocketProperties docket) {
        this.docket = docket;
    }

    public Boolean getEnable() {
        return enable;
    }

    public void setEnable(Boolean enable) {
        this.enable = enable;
    }
}

- ApiInfoProperties

package com.battcn.framework.swagger.properties;

public class ApiInfoProperties implements java.io.Serializable {

    private static final long serialVersionUID = 8471755917762607584L;
    
    private String title;
    private String description;
    private String termsOfServiceUrl;
    private Contact contact;
    private String license;
    private String licenseUrl;
    private String version;
    
    // get set ...
}

- Contact

package com.battcn.framework.swagger.properties;

public class Contact {

    private String name;
    private String url;
    private String email;
    public Contact(){}
    
    public Contact(String name, String url, String email) {
        this.name = name;
        this.url = url;
        this.email = email;
    }
    // get set ...
}

- DocketProperties

package com.battcn.framework.swagger.properties;

public class DocketProperties implements java.io.Serializable {

    private static final long serialVersionUID = 3342663558680329645L;
    
    private String groupName;
    private String basePackage;

    public String getGroupName() {
        return groupName;
    }

    public void setGroupName(String groupName) {
        this.groupName = groupName;
    }

    public String getBasePackage() {
        return basePackage;
    }

    public void setBasePackage(String basePackage) {
        this.basePackage = basePackage;
    }
}

- ApiParamType

package com.battcn.framework.swagger.properties;

/**
 * 方便Swagger 中 @ApiImplicitParam(paramType = ApiParamType.HEADER)
 * @author Levin
 * @Q群：391619659
 */
public final class ApiParamType {
    
    public final static String QUERY = "query";
    public final static String HEADER = "header";
    public final static String PATH = "path";
    public final static String BODY = "body";
    public final static String FORM = "form";
    
}

- 注意

我们需要Spring容器初始化加载我们的 SwaggerAutoConfiguration 那么必须指定初始化类路径，在 src/main/resources
创建一个 META-INF 目录，然后定义一个 spring.factories

如下： = 号的左侧不需要改，右侧为我们 SwaggerAutoConfiguration 的路径

org.springframework.boot.autoconfigure.EnableAutoConfiguration=com.battcn.framework.swagger.SwaggerAutoConfiguration

至此我们自己的starter包就完成了，需要使用到的项目 pom.xml 中 加入我们的starter包

建议是用JDK1.8 SpringBoot1.5.4

<dependency>
    <groupId>com.battcn</groupId>
    <artifactId>battcn-starter-swagger</artifactId>
    <version>1.0.1</version>
</dependency>

- application.yml

#以下就是需要写的配置，注意base-package就可以了    
swagger:
  enable: true    #是否开启swagger/默认false
  api-info:
    description: battcn-plus
    license: battcn-plus
    license-url: http://www.battcn.com
    terms-of-service-url: http://www.battcn.com
    title: 鏖战八方
    version: 2.5.1
    contact:
      email: [e-mail]
      name: Levin
      url: http://www.battcn.com
  docket:
    base-package: com.battcn.platform.controller #扫描的路径/基本就是你的controller包下面
    group-name: battcn-manage

- 项目地址

PS：比如A项目使用了 battcn-starter-swagger 那么只需要输入 http://${host}:${port}/swagger-ui.html 即可