内容简介：接口文档是前后端开发对接时很重要的一个组件。手动编写接口文档既费时，又存在文档不能随代码及时更新的问题，因此产生了像swagger这样的自动生成接口文档的框架。swagger文档一般是随项目代码生成与更新，访问地址也是基于项目地址，因此对项目数不多的团队还好。如果团队的项目很多，比如采用微服务架构的团队，动则几十甚至上百个服务项目，那就意味着前端开发人员需要记住几十甚至上百个swagger文档地址，那就很不友好了。目前貌似还没有较流行的API文档集中化管理项目（也或者是我没找到），因此花了点时间自己集成了一
接口文档是前后端开发对接时很重要的一个组件。手动编写接口文档既费时，又存在文档不能随代码及时更新的问题，因此产生了像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 打开文档页面。如上图，可通过下拉列表来选择不同项目，加载项目的接口文档查看或调试。
项目地址： https://github.com/ronwxy/swagger-register （如果觉得有用，不要吝啬你的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在线接口文档集中管理，有效提高前后端对接效率。
如果觉得本文有用，欢迎转发、推荐。
我的个人博客地址： http://blog.jboost.cn
我的github地址： https://github.com/ronwxy
我的微信公众号：jboost-ksxy （欢迎关注，及时获取技术干货分享）
———————————————————————————————————————————————————————————————
欢迎关注我的微信公众号，及时获取最新分享
以上就是本文的全部内容，希望本文的内容对大家的学习或者工作能带来一定的帮助，也希望大家多多支持 码农网
猜你喜欢:
- 通过ELK快速搭建集中化日志平台
- 关于收集，标准化和集中化处理Golang日志的一些建议
- 关于如何收集，标准化和集中化处理 Golang 日志的一些建议
- 关于如何收集，标准化和集中化处理 Golang 日志的一些建议
- Harbor 任意管理员注册漏洞
- Zookeeper注册中心和Dubbo-Admin管理平台的搭建
本站部分资源来源于网络，本站转载出于传递更多信息之目的，版权归原作者或者来源机构所有，如转载稿涉及版权问题，请联系我们。
Powerful
Patty McCord / Missionday / 2018-1-25
Named by The Washington Post as one of the 11 Leadership Books to Read in 2018 When it comes to recruiting, motivating, and creating great teams, Patty McCord says most companies have it all wrong. Mc......一起来看看 《Powerful》 这本书的介绍吧!
