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

1. swagger-bootstrap-ui项目

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

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

2. swagger api注册服务

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

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

3. 服务端配置

在业务服务端,需要提供一些配置。
首先,需要配置一些Bean,如下提供了一个配置类(这里只列出了主要部分,完整代码参考: https://github.com/ronwxy/base-spring-boot)

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
我的github地址:https://github.com/ronwxy
我的微信公众号:jboost-ksxy (欢迎关注,及时获取技术干货分享)
———————————————————————————————————————————————————————————————

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

最新文章

  1. js连续指定两次或者多次的click事件(解决办法)
  2. Alpha版本十天冲刺——Day 3
  3. 1215课后练习----indexOf的用法
  4. Leetcode | N-Queens I &amp; II
  5. 转 oracle 11g 导出空表
  6. EventBus使用小记
  7. Oracle报错:ORA-01747: user.table.column, table.column 或列说明无效
  8. POJ -- 1151
  9. html》meta标签笔记
  10. STRUCTS 2 LABLE
  11. 对LevelDB的“升级版”存储引擎RocksDB的调研成果
  12. 闭包JS
  13. 关于PLC
  14. 3D Lut 电影级调色算法 附完整C代码
  15. Java开发笔记(四十六)类的构造方法
  16. 在线协作开发工具apizza使用方法(https://apizza.net/projects)
  17. SpringBoot使用日志
  18. 一些Debug时没整理的内容
  19. 第0章 概述及常见dos命令
  20. P1593 因子和

热门文章

  1. 发布与订阅SQLServer
  2. 线性方程组的求解(C++)
  3. less循环写css工具类
  4. eclipes中配置javadoc文档
  5. python 教程 第九章、 类与面向对象
  6. 卷积(convolution)与相关(correlation)(matlab 实现)
  7. 非参贝叶斯(Bayesian Non-parameter)初步
  8. android自定义View绘制天气温度曲线
  9. LeapMotion Demo2
  10. 【转】关于List排序的时效性