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

Mr.white_G

已于 2023-08-10 00:57:54 修改

阅读量86

点赞数 1

文章标签： java spring spring boot

于 2023-05-02 17:30:17 首次发布

原文链接：https://blog.battcn.com/2017/07/13/springboot/springboot-starter-swagger/

版权

文章目录

自定义 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 的路径

1	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: 1837307557@qq.com
      name: Levin
      url: http://www.battcn.com
  docket:
    base-package: com.battcn.platform.controller #扫描的路径/基本就是你的controller包下面
    group-name: battcn-manage