API管理工具Swagger介绍及Springfox原理分析

本文涉及的产品
Serverless 应用引擎 SAE,800核*时 1600GiB*时
云原生网关 MSE Higress,422元/月
性能测试 PTS,5000VUM额度
简介: swagger是一个API框架,号称世界上最流行的API工具。它提供了API管理的全套解决方案,比如API在线编辑器,API UI展示界面,代码生成器等诸多功能。

swagger是一个API框架,号称世界上最流行的API工具。它提供了API管理的全套解决方案,比如API在线编辑器,API UI展示界面,代码生成器等诸多功能。

如果想引入swagger进行API管理。目前 springfox 是一个很好的选择,它内部会自动解析Spring容器中Controller暴露出的接口,并且也提供了一个界面用于展示或调用这些API。下图就是简单的一个使用springfox的API展示界面。

swagger-view.png | center | 748x431

springfox的前身是swagger-springmvc,用于springmvc与swagger的整合。

如若在springboot项目中使用springfox,需要3个步骤:

  1. maven添加springfox依赖
  2. 启动类加上@EnableSwagger2注解
  3. 构造Docket bean用于展示API

配置完之后进入 http://{path}:{port}/swagger-ui.html 即可查看controller中的接口信息,并按照Docket中配置的规则进行展示。

springfox实现原理

在分析springfox实现原理之前,首先看下springfox对文档Documentation的定义:

swagger-documentation.png | center | 748x374

文档Documentation定义得很清晰,主要由groupName(分组名)、basePath(contextPath)、apiListings(API列表集)、resourceListing(资源列表集)等属性组成。

其中API列表被封装成ApiListing。ApiListing中又持有ApiDesciption集合引用,每个ApiDesciption都持有一个API集合的引用,Operation也就是具体的接口操作,内部包含了该接口对应的http方法、produces、consumes、协议、参数集、响应消息集等诸多元素。

springfox通过spring-plugin的方式将Plugin注册到Spring上下文中,然后使用这些plugin进行API的扫描工作,这里的扫描工作其实也就是构造Documentation的工作,把扫描出的结果封装成Documentation并放入到DocumentationCache内存缓存中,之后swagger-ui界面展示的API信息通过Swagger2Controller暴露,Swagger2Controller内部直接从DocumentationCache中寻找Documentation。

下图就是部分Plugin具体构造对应的文档信息:

swagger-class.png | center | 748x638

代码细节方面的分析:

很明显,入口处在@EnableSwagger2注解上,该注解会import一个配置类Swagger2DocumentationConfiguration。

Swagger2DocumentationConfiguration做的事情:

  1. 构造Bean。比如HandlerMapping,HandlerMapping是springmvc中用于处理请求与handler(controller中的方法)之间映射关系的接口,springboot中默认使用的HandlerMapping是RequestMappingHandlerMapping,Swagger2DocumentationConfiguration配置类里构造的是PropertySourcedRequestMappingHandlerMapping,该类继承RequestMappingHandlerMapping。
  2. import其它配置类,比如SpringfoxWebMvcConfiguration、SwaggerCommonConfiguration
  3. 扫描指定包下的类,并注册到Spring上下文中

SpringfoxWebMvcConfiguration配置类做的事情跟Swagger2DocumentationConfiguration类似,不过多了一步构造PluginRegistry过程。该过程使用@EnablePluginRegistries注解实现:

@EnablePluginRegistries({ DocumentationPlugin.class,
    ApiListingBuilderPlugin.class,
    OperationBuilderPlugin.class,
    ParameterBuilderPlugin.class,
    ExpandedParameterBuilderPlugin.class,
    ResourceGroupingStrategy.class,
    OperationModelsProviderPlugin.class,
    DefaultsProviderPlugin.class,
    PathDecorator.class,
    ApiListingScannerPlugin.class
})

@EnablePluginRegistries注解是spring-plugin模块提供的一个基于Plugin类型注册PluginRegistry实例到Spring上下文的注解。

@EnablePluginRegistries注解内部使用PluginRegistriesBeanDefinitionRegistrar注册器去获取注解的value属性(类型为Plugin接口的Class数组);然后遍历这个Plugin数组,针对每个Plugin在Spring上下文中注册PluginRegistryFactoryBean,并设置相应的name和属性。

如果处理的Plugin有@Qualifier注解,那么这个要注册的PluginRegistryFactoryBean的name就是@Qualifier注解的value,否则name就是插件名首字母小写+Registry的格式(比如DocumentationPlugin对应构造的bean的name就是documentationPluginRegistry)。

PluginRegistriesBeanDefinitionRegistrar注册器处理过程:

@Override
public void registerBeanDefinitions(AnnotationMetadata importingClassMetadata, BeanDefinitionRegistry registry) {

   Class<?>[] types = (Class<?>[]) importingClassMetadata.getAnnotationAttributes(
         EnablePluginRegistries.class.getName()).get("value");

   for (Class<?> type : types) {

      BeanDefinitionBuilder builder = BeanDefinitionBuilder.rootBeanDefinition(PluginRegistryFactoryBean.class);
      builder.addPropertyValue("type", type);

      AbstractBeanDefinition beanDefinition = builder.getBeanDefinition();
      Qualifier annotation = type.getAnnotation(Qualifier.class);

      // If the plugin interface has a Qualifier annotation, propagate that to the bean definition of the registry
      if (annotation != null) {
         AutowireCandidateQualifier qualifierMetadata = new AutowireCandidateQualifier(Qualifier.class);
         qualifierMetadata.setAttribute(AutowireCandidateQualifier.VALUE_KEY, annotation.value());
         beanDefinition.addQualifier(qualifierMetadata);
      }

      // Default
      String beanName = annotation == null ? StringUtils.uncapitalize(type.getSimpleName() + "Registry") : annotation
            .value();
      registry.registerBeanDefinition(beanName, builder.getBeanDefinition());
   }
}

PluginRegistryFactoryBean是一个FactoryBean,其内部真正构造的bean的类型是OrderAwarePluginRegistry。OrderAwarePluginRegistry实例化过程中会调用create静态方法,传入的plugin集合使用aop代理生成一个ArrayList,这个list中的元素就是Spring上下文中所有的类型为之前遍历的Plugin的bean。
PluginRegistryFactoryBean的getObject方法:

public OrderAwarePluginRegistry<T, S> getObject() {
   return OrderAwarePluginRegistry.create(getBeans());
}
protected List<T> getBeans() {
   ProxyFactory factory = new ProxyFactory(List.class, targetSource);
   return (List<T>) factory.getProxy();
}

这里的targetSource是在PluginRegistryFactoryBean的父类AbstractTypeAwareSupport(实现了InitializingBean接口)中的afterPropertiesSet方法中初始化的(type属性在PluginRegistriesBeanDefinitionRegistrar注册器中已经设置为遍历的Plugin):

public void afterPropertiesSet() {
   this.targetSource = new BeansOfTypeTargetSource(context, type, false, exclusions);
}

BeansOfTypeTargetSource的getTarget方法:

public synchronized Object getTarget() throws Exception {
   Collection<Object> components = this.components == null ? getBeansOfTypeExcept(type, exclusions)
         : this.components;

   if (frozen && this.components == null) {
      this.components = components;
   }

   return new ArrayList(components);
}

private Collection<Object> getBeansOfTypeExcept(Class<?> type, Collection<Class<?>> exceptions) {
  List<Object> result = new ArrayList<Object>();

  for (String beanName : context.getBeanNamesForType(type, false, eagerInit)) {
    if (exceptions.contains(context.getType(beanName))) {
      continue;
    }
    result.add(context.getBean(beanName));
  }

  return result;
}

举个例子:比如SpringfoxWebMvcConfiguration中的@EnablePluginRegistries注解里的DocumentationPlugin这个Plugin,在处理过程中会找出Spring上下文中所有的Docket(Docket实现了DocumentationPlugin接口),并把该集合设置成name为documentationPluginRegistry、类型为OrderAwarePluginRegistry的bean,注册到Spring上下文中。

DocumentationPluginsManager类会在之前提到过的配置类中被扫描出来,它内部的各个pluginRegistry属性都是@EnablePluginRegistries注解内部构造的各种pluginRegistry实例:

@Component
public class DocumentationPluginsManager {
  @Autowired
  @Qualifier("documentationPluginRegistry")
  private PluginRegistry<DocumentationPlugin, DocumentationType> documentationPlugins;
  @Autowired
  @Qualifier("apiListingBuilderPluginRegistry")
  private PluginRegistry<ApiListingBuilderPlugin, DocumentationType> apiListingPlugins;
  @Autowired
  @Qualifier("parameterBuilderPluginRegistry")
  private PluginRegistry<ParameterBuilderPlugin, DocumentationType> parameterPlugins;
  ...
}

DocumentationPluginsBootstrapper启动类也会在之前提供的配置类中被扫描出来。它实现了SmartLifecycle接口,在start方法中,会获取之前初始化的所有documentationPlugins(也就是Spring上下文中的所有Docket)。遍历这些Docket并进行scan扫描(使用RequestMappingHandlerMapping的getHandlerMethods方法获取url与方法的所有映射关系,然后进行一系列API解析操作),扫描出来的结果封装成Documentation并添加到DocumentationCache中:

@Override
public void start() {
  if (initialized.compareAndSet(false, true)) {
    log.info("Context refreshed");
    List<DocumentationPlugin> plugins = pluginOrdering()
        .sortedCopy(documentationPluginsManager.documentationPlugins());
    log.info("Found {} custom documentation plugin(s)", plugins.size());
    for (DocumentationPlugin each : plugins) {
      DocumentationType documentationType = each.getDocumentationType();
      if (each.isEnabled()) {
        scanDocumentation(buildContext(each));
      } else {
        log.info("Skipping initializing disabled plugin bean {} v{}",
            documentationType.getName(), documentationType.getVersion());
      }
    }
  }
}

以上就是API解析、扫描的大致处理过程,整理如下:

swagger-annotation-process.png | center | 748x444

下面分析一下HandlerMapping的处理过程。

PropertySourcedRequestMappingHandlerMapping在Swagger2DocumentationConfiguration配置类中被构造:

@Bean
public HandlerMapping swagger2ControllerMapping(
    Environment environment,
    DocumentationCache documentationCache,
    ServiceModelToSwagger2Mapper mapper,
    JsonSerializer jsonSerializer) {
  return new PropertySourcedRequestMappingHandlerMapping(
      environment,
      new Swagger2Controller(environment, documentationCache, mapper, jsonSerializer));
}

PropertySourcedRequestMappingHandlerMapping初始化过程中会设置优先级为Ordered.HIGHEST_PRECEDENCE + 1000,同时还会根据Swagger2Controller得到RequestMappingInfo映射信息,并设置到handlerMethods属性中。

PropertySourcedRequestMappingHandlerMapping复写了lookupHandlerMethod方法,首先会去handlerMethods属性中查询是否存在对应的映射关系,没找到的话使用下一个HandlerMapping进行处理:

@Override
protected HandlerMethod lookupHandlerMethod(String urlPath, HttpServletRequest request) throws Exception {
  logger.debug("looking up handler for path: " + urlPath);
  HandlerMethod handlerMethod = handlerMethods.get(urlPath);
  if (handlerMethod != null) {
    return handlerMethod;
  }
  for (String path : handlerMethods.keySet()) {
    UriTemplate template = new UriTemplate(path);
    if (template.matches(urlPath)) {
      request.setAttribute(
          HandlerMapping.URI_TEMPLATE_VARIABLES_ATTRIBUTE,
          template.match(urlPath));
      return handlerMethods.get(path);
    }
  }
  return null;
}

Swagger2Controller中只有一个mapping方法,默认的path值为/v2/api-docs,可以通过配置 springfox.documentation.swagger.v2.path 进行修改。所以默认情况下 /v2/api-docs?group=person-api、/v2/api-docs?group=user-api 这些地址都会被Swagger2Controller所处理。

Swagger2Controller内部获取文档信息会去DocumentationCache中查找:

@RequestMapping(
    value = DEFAULT_URL,
    method = RequestMethod.GET,
    produces = { APPLICATION_JSON_VALUE, HAL_MEDIA_TYPE })
@PropertySourcedMapping(
    value = "${springfox.documentation.swagger.v2.path}",
    propertyKey = "springfox.documentation.swagger.v2.path")
@ResponseBody
public ResponseEntity<Json> getDocumentation(
    @RequestParam(value = "group", required = false) String swaggerGroup,
    HttpServletRequest servletRequest) {

  String groupName = Optional.fromNullable(swaggerGroup).or(Docket.DEFAULT_GROUP_NAME);
  Documentation documentation = documentationCache.documentationByGroup(groupName);
  if (documentation == null) {
    return new ResponseEntity<Json>(HttpStatus.NOT_FOUND);
  }
  Swagger swagger = mapper.mapDocumentation(documentation);
  UriComponents uriComponents = componentsFrom(servletRequest, swagger.getBasePath());
  swagger.basePath(Strings.isNullOrEmpty(uriComponents.getPath()) ? "/" : uriComponents.getPath());
  if (isNullOrEmpty(swagger.getHost())) {
    swagger.host(hostName(uriComponents));
  }
  return new ResponseEntity<Json>(jsonSerializer.toJson(swagger), HttpStatus.OK);
}

引入springfox带来的影响

影响主要有2点:

  1. 应用启动速度变慢,因为额外加载了springfox中的信息,同时内存中也缓存了这些API信息
  2. 多了一个HandlerMapping,并且优先级高。以下是springboot应用DispatcherServlet的HandlerMapping集合。其中springfox构造的PropertySourcedRequestMappingHandlerMapping优先级最高。优先级最高说明第一次查询映射关系都是走PropertySourcedRequestMappingHandlerMapping,而程序中大部分请求都是在RequestMappingHandlerMapping中处理的

屏幕快照 2018-04-02 下午5.56.05.png | center | 590x179

优先级问题可以使用BeanPostProcessor处理,修改优先级:

@Override
public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
    if(beanName.equals("swagger2ControllerMapping")) {
        ((PropertySourcedRequestMappingHandlerMapping) bean).setOrder(Ordered.LOWEST_PRECEDENCE - 1000);
    }
    return bean;
}
相关文章
|
19天前
|
缓存 API 网络架构
Nuxt Kit API :路径解析工具
【9月更文挑战第20天】在 Nuxt Kit API 中,路径解析工具如 `resolvePath()`、`joinPaths()` 和 `relativePath()` 帮助开发者高效处理应用路径,确保资源准确加载,并支持动态路由与组件导入。这些工具提升了应用的灵活性和可扩展性,同时需注意路径准确性、跨平台兼容性和性能优化,以提升用户体验。
27 12
|
1天前
|
API 数据安全/隐私保护 开发者
淘宝 API:关键词搜商品列表接口,助力商家按价格销量排序分析数据
此接口用于通过关键词搜索淘宝商品列表。首先需在淘宝开放平台注册并创建应用获取API权限,之后利用应用密钥和访问令牌调用接口。请求参数包括关键词、页码、每页数量、排序方式及价格区间等。返回结果含总商品数量及具体商品详情。使用时需注意签名验证及官方文档更新。
|
28天前
|
JSON 安全 API
淘宝 API 接口:解锁商品详情的强大工具
淘宝API接口在电商领域扮演着关键角色,为商家和开发者提供强大的数据支持和服务能力。它不仅帮助商家获取商品信息、管理订单和物流,还支持数据分析、价格调整等功能,助力商家在竞争激烈的市场中取得成功。此外,通过注册认证、搭建开发环境等步骤,开发者可快速上手并利用丰富的技术文档和社区支持进行高效开发。
|
2月前
|
存储 Linux API
Linux源码阅读笔记08-进程调度API系统调用案例分析
Linux源码阅读笔记08-进程调度API系统调用案例分析
|
2月前
|
监控 API 数据安全/隐私保护
​邮件API触发式接口分析?邮件API接口好评榜
邮件API在企业通信和营销中至关重要,通过自动化邮件发送流程提升效率与客户满意度。本文解析邮件API触发式接口,即基于特定事件(如用户注册、购买产品)自动发送邮件的技术,能显著加快企业响应速度并增强用户体验。推荐市场上的优秀邮件API产品,包括SendGrid、Mailgun、Amazon SES、Postmark及新兴的AOKSend,它们各具特色,如高发送率、详细分析工具、灵活配置、强大的日志功能及用户友好的API接口,帮助企业根据不同需求选择最合适的邮件API解决方案。
|
2月前
|
XML 开发框架 .NET
ASP.NET Web Api 如何使用 Swagger 管理 API
ASP.NET Web Api 如何使用 Swagger 管理 API
|
3月前
|
JSON API 网络架构
gRPC 与 REST 的比较分析:哪种 API 适合您的开发需求?
gRPC, 由 Google 推出的开源远程过程调用(RPC)框架, 使两个应用程序间的方法调用变得简单,支持结构化数据的交换。通过采用 Protocol Buffers (Protobuf) ——一种与语言无关的接口定义语言,gRPC 体现了许多现代网络通信技术的优势
gRPC 与 REST 的比较分析:哪种 API 适合您的开发需求?
|
2月前
|
UED 开发工具 iOS开发
Uno Platform大揭秘:如何在你的跨平台应用中,巧妙融入第三方库与服务,一键解锁无限可能,让应用功能飙升,用户体验爆棚!
【8月更文挑战第31天】Uno Platform 让开发者能用同一代码库打造 Windows、iOS、Android、macOS 甚至 Web 的多彩应用。本文介绍如何在 Uno Platform 中集成第三方库和服务,如 Mapbox 或 Google Maps 的 .NET SDK,以增强应用功能并提升用户体验。通过 NuGet 安装所需库,并在 XAML 页面中添加相应控件,即可实现地图等功能。尽管 Uno 平台减少了平台差异,但仍需关注版本兼容性和性能问题,确保应用在多平台上表现一致。掌握正确方法,让跨平台应用更出色。
38 0
|
2月前
|
数据采集 API TensorFlow
简化目标检测流程:深入探讨TensorFlow Object Detection API的高效性与易用性及其与传统方法的比较分析
【8月更文挑战第31天】TensorFlow Object Detection API 是一项强大的工具,集成多种先进算法,支持 SSD、Faster R-CNN 等模型架构,并提供预训练模型,简化目标检测的开发流程。用户只需准备数据集并按要求处理,选择预训练模型进行微调训练即可实现目标检测功能。与传统方法相比,该 API 极大地减少了工作量,提供了从数据预处理到结果评估的一站式解决方案,降低了目标检测的技术门槛,使初学者也能快速搭建高性能系统。未来,我们期待看到更多基于此 API 的创新应用。
26 0
|
2月前
|
存储 JavaScript 前端开发
探索React状态管理:Redux的严格与功能、MobX的简洁与直观、Context API的原生与易用——详细对比及应用案例分析
【8月更文挑战第31天】在React开发中,状态管理对于构建大型应用至关重要。本文将探讨三种主流状态管理方案:Redux、MobX和Context API。Redux采用单一存储模型,提供预测性状态更新;MobX利用装饰器语法,使状态修改更直观;Context API则允许跨组件状态共享,无需第三方库。每种方案各具特色,适用于不同场景,选择合适的工具能让React应用更加高效有序。
47 0