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 ...
随机推荐
- cocos2dx内存管理的一些看法
今年年初进入一家游戏公司,正式开始游戏引擎的学习,之前的ios学习,对现在的游戏引擎学习还是有很大的帮助的,虽然使用c++,但却能时刻感受到ios框架对于cocos2dx的巨大影响. 由于之前一直使用 ...
- SQL Server通过整理索引碎片和重建索引提高速度
本文章转载:http://database.51cto.com/art/201108/282408.htm SQL Server数据库中,当索引碎片太多时,就会拖慢数据库查询的速度.这时我们可以通过整 ...
- android设置view透明度的效果
android设置view透明度的效果 推荐textView.setBackgroundColor(Color.TRANSPARENT); 第一种方法:在xml文件中设置背景颜色. andro ...
- Android使用DOM生成和输出XML格式数据
Android使用DOM生成和输出XML格式数据 本文主要简单解说怎样使用DOM生成和输出XML数据. 1. 生成和输出XML数据 代码及凝视例如以下: try { DocumentBuilderFa ...
- [Angular 2] Controlling how Styles are Shared with View Encapsulation
Style and View Encapsulation is best understood by seeing how each option (Emulated, Native, and Non ...
- C#之—委托
(1)定义委托:(百度百科样例,只有写了才有收获) namespace Entrust { public delegate void GreetingDelegate(string name); // ...
- Mock和injectMocks的区别
@Mock private ForeCatalogManageServiceImpl foreCatalogManageServiceImpl; 如果是上面的写法,那么 红框方法里面的代码不会执行,这 ...
- Oracle Pivot学习心得
今天在做一个查询报表需要将多行的查询结果转换成一行,数据格式如下 ID Type Parameter Value Machine_NO Operator UpdateTime 1 11111111 ...
- 动态内存分配(new)和释放(delete)
在之前我们所写过的程序中,所必需的内存空间的大小都是在程序执行之前就已经确定了.但如果我们需要内存大小为一个变量,其数值只有在程序运行时 (runtime)才能确定,例如有些情况下我们需要根据用户输入 ...
- 想追赶.Net的脚步?Java面前障碍重重
待到Java 8面世之时 .Net的进度时钟恐怕已经又走过了两到五年——届时微软做出的调整将使二者差距进一步拉大. 就在几周之前,我详细介绍了Java 8中值得期待的几大主要功能.不过当时我并没有提到 ...