springboot之swagger快速启动
介绍
可能大家都有用过swagger,可以通过ui页面显示接口信息，快速和前端进行联调。
没有接触的小伙伴可以参考官网文章进行了解下demo页面。
多应用
当然在单个应用大家可以配置SwaggerConfig类加载下buildDocket,就可以快速构建好swagger了。
代码大致如下：
/**
* Swagger2配置类
* 在与spring boot集成时，放在与Application.java同级的目录下。
* 通过@Configuration注解，让Spring来加载该类配置。
* 再通过@EnableSwagger2注解来启用Swagger2。
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* 创建API应用
* apiInfo() 增加API相关信息
* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
* 本例采用指定扫描的包路径来定义指定要建立API的目录。
*
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.swaggerTest.controller"))
.paths(PathSelectors.any())
.build();
}
/**
* 创建该API的基本信息（这些基本信息会展现在文档页面中）
* 访问地址：http://项目实际地址/swagger-ui.html
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("更多请关注http://www.baidu.com")
.termsOfServiceUrl("http://www.baidu.com")
.contact("sunf")
.version("1.0")
.build();
}
}
缘由
有开发过微服务的小伙伴应该体会过。当微服务模块多的情况下，每个模块都需要配置这样的一个类进行加载swagger。造成每个模块都存在大致一样的SwaggerConfig,极端的情况下，有些朋友复制其他模块的SwaggerConfig进行改造之后，发现仍然加载不出swagger的情况，造成明明是复制的，为何还加载不出，排查此bug及其费时间。
在此之上，可以构建出一个swagger-starter模块，只需要引用一个jar，加载一些特殊的配置，就可以快速的使用到swagger的部分功能了。
设计
创建模块swagger-spring-boot-starter。
功能大致如下：
加载SwaggerConfig。
通过配置化配置swagger。
Enable加载注解。
1. 创建SwaggerConfig
SwaggerConfig和之前的一致，只是里面的配置需要外部化。
@Configuration
@PropertySource(value = "classpath:swagger.properties", ignoreResourceNotFound = true, encoding = "UTF-8")
@EnableConfigurationProperties(SwaggerProperties.class)
public class SwaggerConfig {
@Resource
private SwaggerProperties swaggerProperties;
@Bean
public Docket buildDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(buildApiInf())
.select()
.apis(RequestHandlerSelectors.basePackage(""))
.paths(PathSelectors.any())
.build();
}
private ApiInfo buildApiInf() {
return new ApiInfoBuilder()
.title(swaggerProperties.getTitle())
.description(swaggerProperties.getDescription())
.termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl())
.contact(new Contact("skyworth", swaggerProperties.getTermsOfServiceUrl(), ""))
.version(swaggerProperties.getVersion())
.build();
}
}
2. 创建SwaggerProperties 配置相关
配置通过@PropertySource注解加载resources目录下的swagger.properties。
创建SwaggerProperties配置类,这个类里包含了一般swagger初始化要使用的一些常用的属性，如扫描包路径、title等等。
@Data
@ToString
@ConfigurationProperties(SwaggerProperties.PREFIX)
public class SwaggerProperties {
public static final String PREFIX = "swagger";
/**
* 文档扫描包路径
*/
private String basePackage = "";
/**
* title 如: 用户模块系统接口详情
*/
private String title = "深兰云平台系统接口详情";
/**
* 服务文件介绍
*/
private String description = "在线文档";
/**
* 服务条款网址
*/
private String termsOfServiceUrl = "https://www.deepblueai.com/";
/**
* 版本
*/
private String version = "V1.0";
}
做好这两件事情基本大工搞成了，为了更好的使用配置，在idea里和官方starter包一样，我们还需要配置一个additional-spring-configuration-metadata.json,让我们自己的配置也具有提示的功能，具体介绍请产考：配置提示 配置提示 配置提示 配置提示 配置提示 ...
image.png
image.png
3. 加载SwaggerConfig等特性
因为是starter模块，可能他人的项目目录和starter模块的目录不一致，导致加载不到SwaggerConfig类，我们需要使用spring.factories把SwaggerConfig类装载到spring容器。
resources/META-INF
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
io.purge.swagger.SwaggerConfig
当然本次基于Enable方式去加载SwaggerConfig。
创建@EnableSwaggerPlugins注解类，使用@Import(SwaggerConfig.class)将SwaggerConfig导入大工搞成。
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Import(SwaggerConfig.class)
@EnableSwagger2
public @interface EnableSwaggerPlugins {
}
添加依赖
把自己编写好的swagger通过maven打包，自己项目引用。
com.purgeteam
swagger-spring-boot-starter
0.1.0.RELEASE
配置swagger.properties文件
在自己项目模块的resources目录下 创建swagger.properties配置
swagger.properties 大致配置如下
swagger.basePackage="swagger扫描项目包路径"
swagger.title="swagger网页显示标题"
swagger.description="swagger网页显示介绍"
启动类添加@EnableSwaggerPlugins注解。
@EnableSwaggerPlugins
@SpringBootApplication
public class FrontDemoApplication {
public static void main(String[] args) {
SpringApplication.run(FrontDemoApplication.class, args);
}
}
访问http://ip:端口/swagger-ui.html检查swagger-ui是否正常。
image.png
简单的starter代码编写可以减少新模块的复杂性，只需要简单的配置就可以使用相应的特性，减少复制代码不必要的错误。
示例代码地址: swagger-spring-boot
__EOF__
作 者：Purgeyao
出 处：https://www.cnblogs.com/Purgeyao
关于博主：大家好，我是purgeyao 一个落寞在魔都的码农。热爱生活，爱读书/旅游，喜欢技术，乐于专研。评论和私信会在第一时间回复。微博 : Purgeyao 知识星球: [小宇宙](https://t.zsxq.com/NFmyVny), GitHub: [Purgeyao](https://github.com/1346735074)
版权声明：署名 - 非商业性使用 - 禁止演绎，协议普通文本 | 协议法律文本。
声援博主：如果您觉得文章对您有帮助，可以点击文章右下角【推荐】一下。您的鼓励是博主的最大动力！
好文要顶 关注我 收藏该文 Purgeyao
关注 - 1
粉丝 - 4
+加关注
0 0
« 上一篇： springboot之additional-spring-configuration-metadata.json自定义提示
» 下一篇： 代码质量检测(SonarQube)整合中文版+阿里P3C
posted @ 2019-09-06 11:46 Purgeyao 阅读(287) 评论(0) 编辑 收藏
https://www.cnblogs.com/Purgeyao/p/11473935.html