Swagger API文档集中化注册管理

接口文档是前后端开发对接时很重要的一个组件。手动编写接口文档既费时，又存在文档不能随代码及时更新的问题，因此产生了像swagger这样的自动生成接口文档的框架。swagger文档一般是随项目代码生成与更新，访问地址也是基于项目地址，因此对项目数不多的团队还好。如果团队的项目很多，比如采用微服务架构的团队，动则几十甚至上百个服务项目，那就意味着前端开发人员需要记住几十甚至上百个swagger文档地址，那就很不友好了。目前貌似还没有较流行的API文档集中化管理项目（也或者是我没找到），因此花了点时间自己集成了一个，介绍如下。

1. swagger-bootstrap-ui项目

该项目是github上的一个开源项目（https://github.com/xiaoymin/swagger-bootstrap-ui
<https://github.com/xiaoymin/swagger-bootstrap-ui> ），对swagger
ui做了增强，功能整体看起来要丰富一些。来看看效果，



该项目的调试url地址原本是基于自身服务的，我将它改为了注册服务的url地址，以支持注册服务的接口调试。调整后的源码地址： 
https://github.com/ronwxy/swagger-bootstrap-ui
<https://github.com/ronwxy/swagger-bootstrap-ui>

2. swagger api注册服务

该项目集成了swagger-bootstrap-ui，并提供了swagger
api注册接口，接受所有提供了有效配置的服务项目注册，让注册的服务在一个页面上可统一查看，再也不用记太多文档地址了。



启动注册服务后，访问 http://localhost:11090/doc.html <http://localhost:11090/doc.html>
 打开文档页面。如上图，可通过下拉列表来选择不同项目，加载项目的接口文档查看或调试。
项目地址： 关注本文最后二维码公众号，回复“swagger”获取源码地址 （一个不只有实战干货的技术公众号，欢迎关注
。如果觉得有用，不要吝啬你的star，反正又不要钱，O(∩_∩)O）

3. 服务端配置

在业务服务端，需要提供一些配置。
首先，需要配置一些Bean，如下提供了一个配置类（这里只列出了主要部分，完整代码参考： 
https://github.com/ronwxy/base-spring-boot）
<https://github.com/ronwxy/base-spring-boot%EF%BC%89>
public class Swagger2AutoConfiguration { @Bean public Docket restApi() {
ParameterBuilder builder= new ParameterBuilder(); builder.name(
"x-auth-token").description("授权token") .modelRef(new ModelRef("string"))
.parameterType("header") .required(false); return new
Docket(DocumentationType.SWAGGER_2) .groupName(groupName) .select()
.apis(RequestHandlerSelectors.basePackage(apisBasePackage))
.paths(PathSelectors.any()) .build()
.globalOperationParameters(Collections.singletonList(builder.build()))
.apiInfo(apiInfo()); } @Profile({"dev"}) @Bean public CommandLineRunner
swaggerRegistar(ConfigurableApplicationContext context) {return new
SwaggerInfoRegistar(context); }/** * use to register swagger api info url to
swagger api registry; * *@author liubo */ public class SwaggerInfoRegistar
implements CommandLineRunner { @Override public void run(String... args) throws
Exception { String url= buildLocalSwaggerDocsUrl();
registerLocalSwaggerUrl(url); }/** * register the v2/api-docs url * * @param url
*/ private void registerLocalSwaggerUrl(String url) { RestTemplate restTemplate
=new RestTemplate(); restTemplate.getMessageConverters().add(new
FormHttpMessageConverter()); MultiValueMap<String, Object> body = new
LinkedMultiValueMap<>(); body.add("project", getApiTitle()); body.add("url",
url); ResponseEntity<Map> re =
restTemplate.postForEntity(getSwaggerRegisterUrl(), body, Map.class); if
(HttpStatus.OK.equals(re.getStatusCode())) { logger.info("swagger api
registered success to {}", getSwaggerRegisterUrl()); } else { logger.warn(
"swagger api registered failed [{}]", re.getBody().get("msg")); } } } }
该类完成了swagger的基本配置，同时将swagger的/v2/api-docs地址注册到了步骤2中介绍的注册服务。 

然后，因为要从注册服务端调用该业务服务的接口进行调试，存在跨域，因此服务需要做跨域支持，配置文件中添加如下定义，
@Bean @ConditionalOnMissingBean(name = "corsFilterRegistrationBean") public
FilterRegistrationBean corsFilterRegistrationBean() {
UrlBasedCorsConfigurationSource corsConfigurationSource= new
UrlBasedCorsConfigurationSource(); CorsConfiguration corsConfiguration= new
CorsConfiguration(); corsConfiguration.applyPermitDefaultValues();
corsConfiguration.setAllowedMethods(Arrays.asList(CorsConfiguration.ALL));
corsConfiguration.addExposedHeader(HttpHeaders.DATE);
corsConfigurationSource.registerCorsConfiguration("/**", corsConfiguration);
CorsFilter corsFilter= new CorsFilter(corsConfigurationSource);
FilterRegistrationBean filterRegistrationBean= new FilterRegistrationBean();
filterRegistrationBean.setFilter(corsFilter);
filterRegistrationBean.setOrder(Ordered.HIGHEST_PRECEDENCE);
filterRegistrationBean.addUrlPatterns("/*"); return filterRegistrationBean; }
 

最后，在属性配置文件application.yml中配置一些必要的属性，
swagger: api-title: Demo标题 #会展示在下拉列表框中，一般写项目名称 api-description: Demo描述，集中注册
group-name: Demo项目 apis-base-package: cn.jboost.springboot.swagger # API类所在包名
swagger-registry-path: http://localhost:11090/swagger/register #就是2中注册服务的注册接口地址
 

配置完后， 就可以像一般项目一样编写接口类，加swagger注解。项目启动时， 会自动向注册服务完成注册，刷新注册服务的文档页面即可在下拉列表看到。

4. 总结

本文介绍了一个基于swagger
ui增强版项目swagger-bootstrap-ui的接口文档集中化管理实现。采用该实现，将所有swagger在线接口文档集中管理，有效提高前后端对接效率。

 

关注本文最后二维码公众号（jboost-ksxy），回复“swagger”获取源码地址 （一个不只有实战干货的技术公众号，欢迎关注，^_^）

 

如果觉得本文有用，欢迎转发、推荐。


我的个人博客地址：http://blog.jboost.cn <http://blog.jboost.cn/>
我的github地址：https://github.com/ronwxy <https://github.com/ronwxy>
我的微信公众号：jboost-ksxy （欢迎关注，及时获取技术干货分享）
———————————————————————————————————————————————————————————————

欢迎关注我的微信公众号，及时获取最新分享

• « 上一篇：linux下x86和arm架构区别
• » 下一篇：CSS样式表的使用