Swagger天天用，背后原理来一次深度解析

先说一说Springfox和Swagger的关系

Swagger 是一种规范。

springfox-swagger 是基于 Spring 生态系统的该规范的实现。

springfox-swagger-ui 是对 swagger-ui 的封装，使得其可以使用 Spring 的服务。

由于工作中遇到需要基于 Swagger Json 做一些处理，但 Swagger Json 的格式不是那么满足需求。

本文springfox-swagger版本号：2.6.0

本文从问题出发，探索涉及的源码。

GET 方法的参数对象第一个问题，当方法是GET请求，但参数是一个自定义 Object，在展示时（生成的JSON）是不包括本 Object 描述的。所以，就要看看什么时候会生成这些 Model 的描述。

万事有始有终，SpringFox始就在：springfox.documentation.spring.web.plugins下的 DocumentationPluginsBootstrapper。

该类实现了 SmartLifecycle 接口，实现此接口且通过@Component注入到容器的bean, 容器初始化后会执行start()方法.

@Component public class DocumentationPluginsBootstrapper implements SmartLifecycle { 接着看 start 方法

@Override public void start() { if (initialized.compareAndSet(false, true)) { // 拿到 DocumentationPlugin 插件 List<DocumentationPlugin> plugins = pluginOrdering() .sortedCopy(documentationPluginsManager.documentationPlugins()); for (DocumentationPlugin each : plugins) { //获取文档类型 DocumentationType documentationType = each.getDocumentationType(); if (each.isEnabled()) { // 启用则扫描生成文档 scanDocumentation(buildContext(each)); } } } } 调用了 buildContext 方法, 通过 Docket 对象创建 DocumentaionContext 对象

private DocumentationContext buildContext(DocumentationPlugin each) { return each.configure(this.defaultContextBuilder(each)); } 再往下走

private DocumentationContextBuilder defaultContextBuilder(DocumentationPlugin each) { DocumentationType documentationType = each.getDocumentationType(); // 获取所有的RequestHnadler List<RequestHandler> requestHandlers = FluentIterable.from(this.handlerProviders).transformAndConcat(this.handlers()).toList(); return this.documentationPluginsManager.createContextBuilder(documentationType, this.defaultConfiguration).requestHandlers(requestHandlers); } handlerProviders 是 RequestHandlerProvider 接口，实现类是 WebMvcRequestHandlerProvider,其中 requestHandlers 方法会接收Spring中的所有请求映射。

接着看 DocumentationContextBuilder的构造过程：documentationPluginsManager.createContextBuilder

public DocumentationContextBuilder createContextBuilder(DocumentationType documentationType, DefaultConfiguration defaultConfiguration) { return defaultsProviders.getPluginFor(documentationType, defaultConfiguration) .create(documentationType) .withResourceGroupingStrategy(resourceGroupingStrategy(documentationType)); } defaultsProviders 是也是一个插件接口 DefaultsProviderPlugin，只有一个实现类DefaultConfiguration，不过该类未使用@Compoent注解，所以需要给一个替换值defaultConfiguration，也就是DefaultConfiguration。在看DefaultConfiguration的create方法：

@Override public DocumentationContextBuilder create(DocumentationType documentationType) { return new DocumentationContextBuilder(documentationType) .operationOrdering(defaults.operationOrdering()) .apiDescriptionOrdering(defaults.apiDescriptionOrdering()) .apiListingReferenceOrdering(defaults.apiListingReferenceOrdering()) .additionalIgnorableTypes(defaults.defaultIgnorableParameterTypes()) .rules(defaults.defaultRules(typeResolver)) .defaultResponseMessages(defaults.defaultResponseMessages()) .pathProvider(new RelativePathProvider(servletContext)) .typeResolver(typeResolver) .enableUrlTemplating(false) .selector(ApiSelector.DEFAULT); } 这里在给DocumentationContextBuilder设置相关参数，至此拿到了 DocumentationContextBuilder

回到上面提到的buildContext方法，defaultContextBuilder方法执行完毕，接下来是 configure

return each.configure(this.defaultContextBuilder(each)); DocumentationPlugin只有一个实现类Docket，到这里就有点熟悉了。Docket对象是我们开发人员在外部通过@Bean来创建的，而外部赋值的对象值，最终都会整合到DocumentationContext。这里的config就是在二次赋值。可以看一下一般自己定义的Docket对象。

public class SwaggerConfig { ... @Bean public Docket docket() { ... return new Docket(DocumentationType.SWAGGER_2) .groupName(SWAGGER_GROUP) .apiInfo(new ApiInfoBuilder().title("xx").version("1.0.0").build()) ...... .select() .apis(basePackage("xxx")) .paths(PathSelectors.any()) .build(); } } 到这里实际只设置了默认的参数。但接口，定义，模型等关键信息等都未初始化。

回到最初start(), 看看scanDocumentation(buildContext(each))的scanDocumentation

private void scanDocumentation(DocumentationContext context) { scanned.addDocumentation(resourceListing.scan(context)); } 其中 scan 位于 ApiDocumentationScanner类

public Documentation scan(DocumentationContext context) { ApiListingReferenceScanResult result = apiListingReferenceScanner.scan(context); ... Multimap<String, ApiListing> apiListings = apiListingScanner.scan(listingContext); ... apiListingReferenceScanner.scan位于 ApiListingReferenceScanner类

public ApiListingReferenceScanResult scan(DocumentationContext context) { ... // 接口选择器在构建Docket时通过.select()默认配置 ApiSelector selector = context.getApiSelector(); // 根据package路径(一般)或注解区分, 过滤筛选掉不符规则的 RequestHandler 接口 Iterable<RequestHandler> matchingHandlers = from(context.getRequestHandlers()) .filter(selector.getRequestHandlerSelector()); for (RequestHandler handler : matchingHandlers) { // 接口分组 resourceGroup = Controller，RequestMapping = method ResourceGroup resourceGroup = new ResourceGroup(handler.groupName(), handler.declaringClass(), 0); RequestMappingContext requestMappingContext = new RequestMappingContext(context, handler); resourceGroupRequestMappings.put(resourceGroup, requestMappingContext); } return new ApiListingReferenceScanResult(asMap(resourceGroupRequestMappings)); } 到这已经拿到了所有接口并进行了分组，其中ArrayListMultimap是guava的方法。

再回到 ApiDocumentationScanner的 scan方法，看 apiListingScanner.scan

public Multimap<String, ApiListing> scan(ApiListingScanningContext context) { ... for (ResourceGroup resourceGroup : sortedByName(requestMappingsByResourceGroup.keySet())) { ... for (RequestMappingContext each : sortedByMethods(requestMappingsByResourceGroup.get(resourceGroup))) { // 循环Controller下的所有接口的实例对象, 拿到该接口的所有Model models.putAll(apiModelReader.read(each.withKnownModels(models))); apiDescriptions.addAll(apiDescriptionReader.read(each)); } each.withKnownModels 是复制对象，主要看apiModelReader.read,读取该接口的 Model 信息。

public Map<String, Model> read(RequestMappingContext context) { // 忽略的class Set<Class> ignorableTypes = newHashSet(context.getIgnorableParameterTypes()); Set<ModelContext> modelContexts = pluginsManager.modelContexts(context); Map<String, Model> modelMap = newHashMap(context.getModelMap()); for (ModelContext each : modelContexts) { markIgnorablesAsHasSeen(typeResolver, ignorableTypes, each); Optional<Model> pModel = modelProvider.modelFor(each); if (pModel.isPresent()) { mergeModelMap(modelMap, pModel.get()); } else { } populateDependencies(each, modelMap); } return modelMap; } 就是从 modelContexts转化为 Model，看看pluginsManager.modelContexts，怎么取modelContexts

public Set<ModelContext> modelContexts(RequestMappingContext context) { DocumentationType documentationType = context.getDocumentationContext().getDocumentationType(); // 构建接口的ModelContext集合 for (OperationModelsProviderPlugin each : operationModelsProviders.getPluginsFor(documentationType)) { each.apply(context); } return context.operationModelsBuilder().build(); } OperationModelsProviderPlugin有两个实现类，通过文档类型来获取。

OperationModelsProviderPlugin：处理返回类型，参数类型等 SwaggerOperationModelsProvider：swagger注解提供的值类型，@ApiResponse，@ApiOperation等先看OperationModelsProviderPlugin

@Override public void apply(RequestMappingContext context) { // 收集返回类型 collectFromReturnType(context); // 收集参数类型 collectParameters(context); // 收集接口型号 collectGlobalModels(context); } 到了这，本问题（ GET 方法的请求Object不描述）的答案就要呼之欲出了。来看 collectParameters

private void collectParameters(RequestMappingContext context) { // 获取所有类型 List<ResolvedMethodParameter> parameterTypes = context.getParameters(); for (ResolvedMethodParameter parameterType : parameterTypes) { // 过滤
if (parameterType.hasParameterAnnotation(RequestBody.class) || parameterType.hasParameterAnnotation(RequestPart.class)) { ResolvedType modelType = context.alternateFor(parameterType.getParameterType()); context.operationModelsBuilder().addInputParam(modelType); } } } 破案了，可以看到过滤时只会处理两种：通过@RequestBody和@ReuqestPart注解标注的, 而GET方法的参数是不可以使用这两个注解的。（当然从规范来说，GET方法也不应该这种参数）。

至于OperationModelsProviderPlugin的另一个实现类SwaggerOperationModelsProvider主要是收集使用@ApiOperation时主句属性值和@ApiResponse响应状态码涉及到的型号，不再详细列出。

而apiModelReader.read中的 modelContexts转化为 Model的modelProvider.modelFor()是通过ModelProvider实现，下一个问题会详细阐述。

那么，如何解决这个问题：

使用 Docket的additionalModels方法，在配置类中注入 TypeResolver return new Docket(DocumentationType.SWAGGER_2) .additionalModels(typeResolver.resolve(xxx)) ... 借助第三方类库如swagger-bootstrap-ui的工具类（我没接，但可以..）重写重写OperationModelsProviderPlugin的apply方法，添加自定义收集器。或者直接重写 collectParameters也行。比如

private void collectGetParameters(RequestMappingContext context) { ... for (ResolvedMethodParameter parameterType : parameterTypes) { // 不存在@RequestBody注解 if (!parameterType.hasParameterAnnotation(RequestBody.class)...) { ... if (xxx) { ResolvedType modelType = context.alternateFor(parameterType.getParameterType()); context.operationModelsBuilder().addInputParam(modelType); } } ... }} 问题解决。

Enum的描述格式问题是对于枚举类，在生成的JSON文件中描述是在原参数对象中的如下格式：

"xxx": {...} "periodUnit":{ "type":"string", "enum":[ "MINUTE", "HOUR" ... ]} 一般枚举使用会如MINUTE(1,“分钟”),也就是包括了code和name描述。

但实际enum的值会是二者之一。且不会生成如下的可重用的外部引用。

"schema":{ "$ref":"#/definitions/xxxForm" } 注意：可重用的问题在3.0+可以通过配置处理。

如果需要强制将enum的值设为code或name，或拓展更多的内容，就需要来看看，enum类何时会被处理。

上一个问题的结尾说到apiModelReader.read， modelContexts转化为 Model的modelProvider.modelFor()方法是通过ModelProvider实现，其实 ModelProvider`是接口，有两个实现类：

DefaultModelProvider：默认，每次都会将modelContext转换为model CachingModelProvider：声明了guava缓存池，先从缓存池取，没有则调用初始化处理器，转换为模型，再放入缓存池。在ApiModelReader的构造方法里指定了使用CachingModelProvider,不过第一次调用缓存里是没有的，所以往下走到populateDependencies

private void populateDependencies(ModelContext modelContext, Map<String, Model> modelMap) { Map<String, Model> dependencies = modelProvider.dependencies(modelContext); for (Model each : dependencies.values()) { mergeModelMap(modelMap, each); } } CachingModelProvider的dependencies依赖的是DefaultModelProvider的

public Map<String, Model> dependencies(ModelContext modelContext) { return delegate.dependencies(modelContext); } 所以看DefaultModelProvider中的实现

public Map<String, Model> dependencies(ModelContext modelContext) { Map<String, Model> models = newHashMap(); for (ResolvedType resolvedType : dependencyProvider.dependentModels(modelContext)) { ModelContext parentContext = ModelContext.fromParent(modelContext, resolvedType); Optional<Model> model = modelFor(parentContext).or(mapModel(parentContext, resolvedType)); if (model.isPresent()) { models.put(model.get().getName(), model.get()); } } return models; } dependencyProvider.dependentModels和上面一个路子，一默认一缓存，交替接口。

public Set<ResolvedType> dependentModels(ModelContext modelContext) { return from(resolvedDependencies(modelContext)) .filter(ignorableTypes(modelContext)) .filter(not(baseTypes(modelContext))) .toSet(); } 后面是两个过滤，暂且不提。看resolvedDependencies

private List<ResolvedType> resolvedDependencies(ModelContext modelContext) { ... List<ResolvedType> dependencies = newArrayList(resolvedTypeParameters(modelContext, resolvedType)); dependencies.addAll(resolvedArrayElementType(modelContext, resolvedType)); dependencies.addAll(resolvedPropertiesAndFields(modelContext, resolvedType)); ... } 这里都是在构造拓展类型 ResolvedType,有一个叫resolvedPropertiesAndFields,看名字就是它了，进去

private List<ResolvedType> resolvedPropertiesAndFields(ModelContext modelContext, ResolvedType resolvedType) { ... List<ResolvedType> properties = newArrayList(); for (ModelProperty property : nonTrivialProperties(modelContext, resolvedType)) { ... properties.addAll(maybeFromCollectionElementType(modelContext, property)); properties.addAll(maybeFromMapValueType(modelContext, property)); properties.addAll(maybeFromRegularType(modelContext, property)); }} 看到ModelProperty,也就是对象内部属性代表的Model了，那就看nonTrivialProperties方法

private FluentIterable<ModelProperty> nonTrivialProperties(ModelContext modelContext, ResolvedType resolvedType) { return from(propertiesFor(modelContext, resolvedType)) .filter(not(baseProperty(modelContext))); } 之后是propertiesFor

private List<ModelProperty> propertiesFor(ModelContext modelContext, ResolvedType resolvedType) { return propertiesProvider.propertiesFor(resolvedType, modelContext); } 这个propertiesProvider.propertiesFor仍是一cache一default的策略，直接看实现

public List<ModelProperty> propertiesFor(ResolvedType type, ModelContext givenContext) { ... for (Map.Entry<String, BeanPropertyDefinition> each : propertyLookup.entrySet()) { BeanPropertyDefinition jacksonProperty = each.getValue(); Optional<AnnotatedMember> annotatedMember = Optional.fromNullable(safeGetPrimaryMember(jacksonProperty)); if (annotatedMember.isPresent()) { properties.addAll(candidateProperties(type, annotatedMember.get(), jacksonProperty, givenContext)); } }... } 可以看到 List<ModelProperty>通过 candidateProperties方法获取

@VisibleForTesting List<ModelProperty> candidateProperties( ResolvedType type, AnnotatedMember member, BeanPropertyDefinition jacksonProperty, ModelContext givenContext) { List<ModelProperty> properties = newArrayList(); if (member instanceof AnnotatedMethod) { properties.addAll(findAccessorMethod(type, member) .transform(propertyFromBean(givenContext, jacksonProperty)) .or(new ArrayList<ModelProperty>())); } else if (member instanceof AnnotatedField) { properties.addAll(findField(type, jacksonProperty.getInternalName()) .transform(propertyFromField(givenContext, jacksonProperty)) .or(new ArrayList<ModelProperty>())); } else if (member instanceof AnnotatedParameter) { ModelContext modelContext = ModelContext.fromParent(givenContext, type); properties.addAll(fromFactoryMethod(type, jacksonProperty, (AnnotatedParameter) member, modelContext)); } ... } 这里根据 AnnotatedMember判断类成员的类型，进行不同的处理。enum使用的是 propertyFromBean

... public List<ModelProperty> apply(ResolvedMethod input) { ResolvedType type = paramOrReturnType(typeResolver, input); if (!givenContext.canIgnore(type)) { if (shouldUnwrap(input)) { return propertiesFor(type, fromParent(givenContext, type)); } return newArrayList(beanModelProperty(input, jacksonProperty, givenContext)); }... }}; 接着是 beanModelProperty

private ModelProperty beanModelProperty( ... return schemaPluginsManager.property( new ModelPropertyContext(propertyBuilder, jacksonProperty, typeResolver, ... 最后调用了 schemaPluginsManager.property

public ModelProperty property(ModelPropertyContext context) { // 根据文档类型取出 ModelPropertyBuilderPlugin for (ModelPropertyBuilderPlugin enricher : propertyEnrichers.getPluginsFor(context.getDocumentationType())) { enricher.apply(context); } return context.getBuilder().build(); } ModelPropertyBuilderPlugin是一个接口，看它的其中一个实现类ApiModelPropertyPropertyBuilder public void apply(ModelPropertyContext context) { // 取出元素的注解 Optional<ApiModelProperty> annotation = Optional.absent(); ... if (annotation.isPresent()) { context.getBuilder() .allowableValues(annotation.transform(toAllowableValues()).orNull()) .required(annotation.transform(toIsRequired()).or(false)) .readOnly(annotation.transform(toIsReadOnly()).or(false)) .description(annotation.transform(toDescription()).orNull()) .isHidden(annotation.transform(toHidden()).or(false)) .type(annotation.transform(toType(context.getResolver())).orNull()) .position(annotation.transform(toPosition()).or(0)) .example(annotation.transform(toExample()).orNull()); } } 可以看到通过判断是否存在注解，再设置具体的配置。

其中type就是enum展示的类型了，可以固定。allowableValues就是enum的value,可以自定义，还可以加入description.

具体实现可以通过重写ApiModelPropertyPropertyBuilder的apply实现。

到这里，两个问题都得到解决。Springfox的加载过程也基本介绍了一遍。最新2021整理收集的一些高频面试题（都整理成文档），有很多干货，包含mysql，netty，spring，线程，spring cloud、jvm、源码、算法等详细讲解，也有详细的学习规划图，面试题整理等，需要获取这些内容的朋友请点击这里即可！