SpringBoot编写自己的Starter项目(battcn-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(去掉这几个字字,因为URL渲染有问题)://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>
<springboot-admin.version>1.5.1</springboot-admin.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 记得将http..改为http spring4all代码中URL渲染有点问题 -->
<repositories>
<repository>
<id>public</id>
<name>local private nexus</name>
<url>http
..(修改成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..(修改成http)://maven.aliyun.com/nexus/content/groups/public/</url>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>false</enabled>
</snapshots>
</pluginRepository>
</pluginRepositories>
<!--配置maven阿里云结束 -->

 
- 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;

public String getTitle() {
return title;
}

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

public String getDescription() {
return description;
}

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

public String getTermsOfServiceUrl() {
return termsOfServiceUrl;
}

public void setTermsOfServiceUrl(String termsOfServiceUrl) {
this.termsOfServiceUrl = termsOfServiceUrl;
}

public Contact getContact() {
return contact;
}

public void setContact(Contact contact) {
this.contact = contact;
}

public String getLicense() {
return license;
}

public void setLicense(String license) {
this.license = license;
}

public String getLicenseUrl() {
return licenseUrl;
}

public void setLicenseUrl(String licenseUrl) {
this.licenseUrl = licenseUrl;
}

public String getVersion() {
return version;
}

public void setVersion(String version) {
this.version = version;
}

}

- 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;
}

public String getName() {
return name;
}

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

public String getUrl() {
return url;
}

public void setUrl(String url) {
this.url = url;
}

public String getEmail() {
return email;
}

public void setEmail(String email) {
this.email = email;
}

}
 
- 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: 1837307557@qq.com
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 即可

博客:http://blog.battcn.com/
原文链接:http://blog.battcn.com/2017/07/13/starter-swagger/
项目GIT地址: http://git.oschina.net/battcn/battcn-starter-swagger  
 

 

3 个评论

如果有什么好的建议可以及时联系我..
非常好,学习了.已用在工作中.赞.logback是否也能这么写呢?如果可以写,能否给个思路,怎么start...
logback可以在application.yml中配置呀,可以参考官方的

要回复文章请先登录注册