编写自己的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://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: 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 即可
