接口文档是前后端开发对接时很重要的一个组件. 手动编写接口文档既费时, 又存在文档不能随代码及时更新的问题, 因此产生了像 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.YAML 中配置一些必要的属性,
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 (欢迎关注, 及时获取技术干货分享)
---------------------------------------------------------------
来源: https://www.cnblogs.com/spec-dog/p/11104472.html