Configure swagger with spring boot
If you haven’t starting working with spring boot yet, you will quickly find that it pulls out all the common configuration from across your applications. Recently I helped in an effort to modularize configuration and worked on creating a spring-boot-swagger starter project. This project, like other boot modules, would be included in the pom and you would enjoy the fruits of auto configuration.
If you aren't familiar with swagger, swagger is a "specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services". It has various integration points with java back end technologies (JAX-RS, scala, php, nodejs, etc) but even better it has separated the front end into a project called swagger-ui. So as long as your service complies to the spec you can have a pretty UI on top of your rest services. It does lack official support spring MVC though there are various projects on github that attempt to integrate the two, even I started a project. Also there has been talk in spring’s JIRA about swagger support.
We went with swagger-springmc simply due to the number of watchers/stars and it fit in pretty good with little effort. It can be integrated with traditional spring XML or through java config both ways requiring two properties to be set to specify the API version and the base path. With the direction of spring-boot, we wanted to abstract the dependency and defaults so consuming apps would just have to plug it in to the pom.xml. It lead us down a few options which we described below and in the end landed on #3 of Injecting ConfigurableApplicationContext in one of our auto configuration classes.
Option 1 - PropertyPlaceholderConfigurer
As martypitt / swagger-springmvc states in the documentation you can configure the properties programmatically with the PropertyPlaceholderConfigurer. We need the properties in spring's Environment class, a class that manages profiles and properties, but PropertyPlaceholderConfigurer is not able to add properties to environment. PropertySourcesPlaceholderConfigurer uses Environment and not vice versa. Also, we wanted this in the spring boot module, not all consuming rest applications. In case this works for you, this is what the configuration would look like:
@Bean
public static PropertyPlaceholderConfigurer swaggerProperties() throws UnknownHostException {
// Swagger expects these to property values to be replaced. We don't want to propagate these to consumers of
// this configuration, so we derive reasonable defaults here and configure the properties programmatically.
Properties properties = new Properties();
properties.setProperty("documentation.services.basePath", servletContext.getContextPath());
// this property will be overridden at runtime, so the value here doesn't matter
properties.setProperty("documentation.services.version", "REPLACE-ME");
PropertyPlaceholderConfigurer configurer = new PropertyPlaceholderConfigurer();
configurer.setProperties(properties);
configurer.setIgnoreUnresolvablePlaceholders(true);
return configurer;
}
Option 2 - Implementing ApplicationContextInitializer
ApplicationContextInitializer is a call back interface for initializing ConfigurableApplicationContext prior to being refreshed typically used within web applications that require some programmatic initialization of the application context. So this would work great, on start up we can set the two properties but what it doesn't give us is the ability to get hold of a ServletContext through ServletContextAware because it fires to early on in the spring lifecycle.
So if your application will deploy to a single environment or if you want to require each of your applications to specify the properties required in the application.properties file, this solution might work for you. It would look something like this:
In your spring.factories within your boot starter project you would need to add:
org.springframework.context.ApplicationContextInitializer=com.levelup.SomeInitializer
Then add the following class
public class SwaggerApplicationContextInitializer implements
ApplicationContextInitializer<ConfigurableApplicationContext> {
@Override
public void initialize(ConfigurableApplicationContext applicationContext) {
MutablePropertySources propertySources = applicationContext
.getEnvironment().getPropertySources();
Map<String, Object> propertyMap = new HashMap<String, Object>();
propertyMap.put("documentation.services.basePath",
"http://localhost:8080/participant");
propertyMap.put("documentation.services.version", "REPLACE-ME");
propertySources.addFirst(new MapPropertySource(
"documentation.services", propertyMap));
}
}
Option 3 - Injecting ConfigurableApplicationContext
At the end of the day this solution may not be spring certified and there probably another way to do it but worked. ConfigurableApplicationContext classprovides facilities to configure an application context in addition to the application context client methods. So we created a class that implements InitializingBean that allows us to react once all their properties have been set. It allows us to configure the properties need and then add them to the environment so when the DocumentationConfig looks for them, they are available.
@Configuration
@AutoConfigureBefore(SwaggerAutoConfiguration.class)
@EnableConfigurationProperties({ SwaggerBeanProperties.class })
public class SwaggerPropertiesAutoConfiguration implements InitializingBean,
ServletContextAware {
private ServletContext servletContext;
@Autowired
ConfigurableApplicationContext applicationContext;
@Autowired
SwaggerBeanProperties swaggerBeanProperties;
@Override
public void afterPropertiesSet() throws Exception {
MutablePropertySources propertySources = applicationContext
.getEnvironment().getPropertySources();
Map<String, Object> propertyMap = new HashMap<String, Object>();
propertyMap.put("documentation.services.basePath",
getDocumentBasePath());
propertyMap.put("documentation.services.version", getDocumentVersion());
propertySources.addFirst(new MapPropertySource(
"documentation.services", propertyMap));
}
private String getDocumentBasePath() {
if (swaggerBeanProperties.getBasePath() != null) {
return swaggerBeanProperties.getBasePath();
} else {
return servletContext.getContextPath();
}
}
private String getDocumentVersion() {
if (swaggerBeanProperties.getVersion() != null) {
return swaggerBeanProperties.getVersion();
} else {
return "1.0";
}
}
@Override
public void setServletContext(ServletContext servletContext) {
this.servletContext = servletContext;
}
}
We all have heard it before, "we don't want the base configuration" so we created a @ConfigurationProperties class that will look for the properties and will be injected into SwaggerPropertiesAutoConfiguration above. If properties are set in the application we will apply them, otherwise we will look for the defaults in hopes to create consistency across all apps.
@AutoConfigureBefore(SwaggerPropertiesAutoConfiguration.class)
@ConfigurationProperties(name = "documentation.services", ignoreUnknownFields = true)
public class SwaggerBeanProperties {
private String basePath;
private String version;
public String getBasePath() {
return basePath;
}
public void setBasePath(String basePath) {
this.basePath = basePath;
}
public String getVersion() {
return version;
}
public void setVersion(String version) {
this.version = version;
}
}
The last class was simply to import the DocumentationConfig.class
@Configuration
@Import(DocumentationConfig.class)
public class SwaggerAutoConfiguration {
}
Finally, the spring.factories
# Auto Configure
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
boot.web.swagger.autoconfigure.SwaggerAutoConfiguration,\
boot.web.swagger.autoconfigure.SwaggerPropertiesAutoConfiguration
org.springframework.context.ApplicationContextInitializer=
Spring-boot was made to solve the "we have ever which way to configure an application" syndrome but occasionally you still might have get dirty. It might not be perfect but it works for now. If you have suggestions or other ways this could be handled, let me know.
Configure swagger with spring boot posted by Justin Musgrove on 16 April 2014
http://www.leveluplunch.com/blog/2014/04/16/spring-boot-swagger-springmvc-configuration/
Configure swagger with spring boot的更多相关文章
- 使用Swagger生成Spring Boot REST客户端(支持Feign)(待实践)
如果项目上使用了Swagger做RESTful的文档,那么也可以通过Swagger提供的代码生成器生成客户端代码,同时支持Feign客户端. 但是经过测试,生成Feign代码和REST客户端有些臃肿. ...
- Swagger Learing - Spring Boot 整合swagger
学习了一下swagger. 这是编写的Demo 源码 https://github.com/AmberBar/Learning/tree/master/swagger-learning/swagger ...
- Spring Boot初识(3)- Spring Boot整合Swagger
一.本文介绍 如果Web项目是完全前后端分离的话(我认为现在完全前后端分离已经是趋势了)一般前端和后端交互都是通过接口的,对接口入参和出参描述的文档就是Mock文档.随着接口数量的增多和参数的个数增加 ...
- Spring Boot 2.x基础教程:Swagger接口分类与各元素排序问题详解
之前通过Spring Boot 2.x基础教程:使用Swagger2构建强大的API文档一文,我们学习了如何使用Swagger为Spring Boot项目自动生成API文档,有不少用户留言问了关于文档 ...
- Spring Boot 集成 Swagger 生成 RESTful API 文档
原文链接: Spring Boot 集成 Swagger 生成 RESTful API 文档 简介 Swagger 官网是这么描述它的:The Best APIs are Built with Swa ...
- Spring Boot实战:集成Swagger2
一.Swagger简介 上一篇文章中我们介绍了Spring Boot对Restful的支持,这篇文章我们继续讨论这个话题,不过,我们这里不再讨论Restful API如何实现,而是讨论Restful ...
- Developing JSF applications with Spring Boot
Developing JSF applications with Spring Boot Spring Boot can leverage any type of applications, not ...
- Spring Boot文档维护:集成Swagger2
一.Swagger简介 在日常的工作中,我们往往需要给前端(WEB端.IOS.Android)或者第三方提供接口,这个时我们就需要提供一份详细的API说明文档.但维护一份详细的文档可不是一件简单的事情 ...
- Spring Boot 入门系列(二十二)使用Swagger2构建 RESTful API文档
前面介绍了如何Spring Boot 快速打造Restful API 接口,也介绍了如何优雅的实现 Api 版本控制,不清楚的可以看我之前的文章:https://www.cnblogs.com/zha ...
随机推荐
- c# mongo 返回指定的列
var query= db.GetCollection<Merchant>("merchant").Find(Query<Merchant>.EQ(m =& ...
- android抓包工具
下载 http://gdown.baidu.com/data/wisegame/2158469c63492e89/Tcpzhuabao_2.apk
- poj2993 poj2669
扯淡题. 2993 #include <iostream> #include <stdio.h> #include <string> #include <st ...
- Python多进程使用
[Python之旅]第六篇(六):Python多进程使用 香飘叶子 2016-05-10 10:57:50 浏览190 评论0 python 多进程 多进程通信 摘要: 关于进程与线程的对比, ...
- 简单说明Python中的装饰器的用法
简单说明Python中的装饰器的用法 这篇文章主要简单说明了Python中的装饰器的用法,装饰器在Python的进阶学习中非常重要,示例代码基于Python2.x,需要的朋友可以参考下 装饰器对与 ...
- redisbook笔记——redis内存映射数据结构
虽然内部数据结构非常强大,但是创建一系列完整的数据结构本身也是一件相当耗费内存的工作,当一个对象包含的元素数量并不多,或者元素本身的体积并不大时,使用代价高昂的内部数据结构并不是最好的办法. 为了解决 ...
- JS遍历对象或者数组
一.纯js实现 <script> var obj = {"player_id":"GS001","event_id":" ...
- CSS3 @font-face使用实例
Windows10操作系统使用实例: 1.准备好对应格式的字体库 2.方正字体使用实例 <!DOCTYPE html> <html> <head> <meta ...
- 7——使用TextView实现跑马灯
首先给TextView添加一个单行限制: android:singleLine="true" - 解决方案一 更改TextView的一个属性: android:ellipsize= ...
- 标量类型(scalar)
(ISO C11 §6.2.5) Arithmetic types and pointer types are collectively called scalar types. Array and ...