文章目录
自定义
starter
项目,方便其他地方调用,类似spring.datasource.url
这种,本次以自己封装的battcn-starter-swagger
为案例
创建一个Maven工程 battcn-starter-swagger
- pom.xml
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 | <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
自动装配类
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 | 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正确识别,然后可以依赖注入
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | 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
1 2 3 4 5 | <dependency> <groupId>com.battcn</groupId> <artifactId>battcn-starter-swagger</artifactId> <version>1.0.1</version> </dependency> |
- application.yml
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | #以下就是需要写的配置,注意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 即可
博客:鏖战八方
项目GIT地址: battcn-starter-swagger: battcn-starter-swagger —— 简化SpringBoot中繁琐的配置,自动装配,依赖即用