Added ApiListScannerPlugin to allow custom ApiDescriptions

dilipkrish · dilipkrish · commit 1bb340c49187 · 2016-09-25T11:52:21.000-05:00
fixes springfox#1335
diff --git a/docs/asciidoc/extensibility.adoc b/docs/asciidoc/extensibility.adoc
@@ -30,6 +30,9 @@ To explicitly state the extensibility points that are available:
 |===
 |Name| Description
 
+| `ApiListingScannerPlugin`
+| for adding custom api descriptions
+
 | `ApiListingBuilderPlugin`
 | for enriching api listings
 
diff --git a/springfox-spi/src/main/java/springfox/documentation/spi/service/ApiListingScannerPlugin.java b/springfox-spi/src/main/java/springfox/documentation/spi/service/ApiListingScannerPlugin.java
@@ -0,0 +1,37 @@
+/*
+ *
+ *  Copyright 2016 the original author or authors.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ *
+ */
+package springfox.documentation.spi.service;
+
+import org.springframework.plugin.core.Plugin;
+import springfox.documentation.service.ApiDescription;
+import springfox.documentation.spi.DocumentationType;
+import springfox.documentation.spi.service.contexts.DocumentationContext;
+
+import java.util.List;
+
+public interface ApiListingScannerPlugin extends Plugin<DocumentationType> {
+  /**
+   * Implement this method to manually add ApiDescriptions
+   *
+   * @param context - Documentatio ncontext that can be used infer documentation context
+   * @see springfox.documentation.service.ApiDescription
+   * @return List of {@link ApiDescription}
+   */
+  List<ApiDescription> apply(DocumentationContext context);
+}
diff --git a/springfox-spring-web/src/main/java/springfox/documentation/spring/web/plugins/DocumentationPluginsManager.java b/springfox-spring-web/src/main/java/springfox/documentation/spring/web/plugins/DocumentationPluginsManager.java
@@ -20,17 +20,21 @@
 package springfox.documentation.spring.web.plugins;
 
 import com.google.common.base.Function;
+import com.google.common.base.Optional;
+import com.google.common.collect.Lists;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.beans.factory.annotation.Qualifier;
 import org.springframework.plugin.core.PluginRegistry;
 import org.springframework.stereotype.Component;
+import springfox.documentation.service.ApiDescription;
 import springfox.documentation.service.ApiListing;
 import springfox.documentation.service.Operation;
 import springfox.documentation.service.Parameter;
 import springfox.documentation.service.PathDecorator;
 import springfox.documentation.spi.DocumentationType;
 import springfox.documentation.spi.schema.contexts.ModelContext;
 import springfox.documentation.spi.service.ApiListingBuilderPlugin;
+import springfox.documentation.spi.service.ApiListingScannerPlugin;
 import springfox.documentation.spi.service.DefaultsProviderPlugin;
 import springfox.documentation.spi.service.DocumentationPlugin;
 import springfox.documentation.spi.service.ExpandedParameterBuilderPlugin;
@@ -47,7 +51,9 @@
 import springfox.documentation.spi.service.contexts.PathContext;
 import springfox.documentation.spi.service.contexts.RequestMappingContext;
 import springfox.documentation.spring.web.SpringGroupingStrategy;
+import springfox.documentation.spring.web.scanners.ApiListingScanningContext;
 
+import java.util.Collection;
 import java.util.List;
 import java.util.Set;
 
@@ -85,6 +91,10 @@ public class DocumentationPluginsManager {
   @Qualifier("pathDecoratorRegistry")
   private PluginRegistry<PathDecorator, DocumentationContext> pathDecorators;
 
+  @Autowired(required = false)
+  @Qualifier("apiListingScannerPluginRegistry")
+  private PluginRegistry<ApiListingScannerPlugin, DocumentationType> apiListingScanners;
+
   public Iterable<DocumentationPlugin> documentationPlugins() throws IllegalStateException {
     List<DocumentationPlugin> plugins = documentationPlugins.getPlugins();
     ensureNoDuplicateGroups(plugins);
@@ -170,4 +180,20 @@ public Function<String, String> apply(PathDecorator input) {
       }
     };
   }
+
+  public Collection<ApiDescription> additionalListings(final ApiListingScanningContext context) {
+    final DocumentationType documentationType = context.getDocumentationContext().getDocumentationType();
+    return Optional.fromNullable(apiListingScanners)
+        .transform(new Function<PluginRegistry<ApiListingScannerPlugin,DocumentationType>, List<ApiDescription>>() {
+          @Override
+          public List<ApiDescription> apply(PluginRegistry<ApiListingScannerPlugin, DocumentationType> input) {
+            List<ApiDescription> additional = newArrayList();
+            for(ApiListingScannerPlugin each : input.getPluginsFor(documentationType)) {
+              additional.addAll(each.apply(context.getDocumentationContext()));
+            }
+            return additional;
+          }
+        })
+        .or(Lists.<ApiDescription>newArrayList());
+  }
 }
diff --git a/springfox-spring-web/src/main/java/springfox/documentation/spring/web/scanners/ApiDescriptionReader.java b/springfox-spring-web/src/main/java/springfox/documentation/spring/web/scanners/ApiDescriptionReader.java
@@ -55,8 +55,6 @@ public ApiDescriptionReader(
   }
 
   public List<ApiDescription> read(RequestMappingContext outerContext) {
-//    RequestMappingInfo requestMappingInfo = outerContext.getRequestMappingInfo();
-//    HandlerMethod handlerMethod = outerContext.getHandlerMethod();
     PatternsRequestCondition patternsCondition = outerContext.getPatternsCondition();
     ApiSelector selector = outerContext.getDocumentationContext().getApiSelector();
 
diff --git a/springfox-spring-web/src/main/java/springfox/documentation/spring/web/scanners/ApiListingScanner.java b/springfox-spring-web/src/main/java/springfox/documentation/spring/web/scanners/ApiListingScanner.java
@@ -88,7 +88,7 @@ public Multimap<String, ApiListing> scan(ApiListingScanningContext context) {
         models.putAll(apiModelReader.read(each.withKnownModels(models)));
         apiDescriptions.addAll(apiDescriptionReader.read(each));
       }
-
+      apiDescriptions.addAll(pluginsManager.additionalListings(context));
 
       List<ApiDescription> sortedApis = newArrayList(apiDescriptions);
       Collections.sort(sortedApis, documentationContext.getApiDescriptionOrdering());
diff --git a/springfox-spring-web/src/test/groovy/springfox/documentation/spring/web/mixins/ServicePluginsSupport.groovy b/springfox-spring-web/src/test/groovy/springfox/documentation/spring/web/mixins/ServicePluginsSupport.groovy
@@ -49,6 +49,7 @@ class ServicePluginsSupport {
     plugins.resourceGroupingStrategies = create([])
     plugins.operationModelsProviders = create([new OperationModelsProvider(resolver)])
     plugins.defaultsProviders = create([])
+    plugins.apiListingScanners = create([])
     plugins.pathDecorators = create([
         new OperationPathDecorator(),
         new PathSanitizer(),
@@ -78,6 +79,7 @@ class ServicePluginsSupport {
     plugins.operationModelsProviders = create([new OperationModelsProvider(resolver)])
     plugins.defaultsProviders = create(defaultProviderPlugins)
     plugins.pathDecorators = create(pathDecorators)
+    plugins.apiListingScanners = create([])
     return plugins
   }
 
diff --git a/springfox-swagger-common/src/test/groovy/springfox/documentation/swagger/mixins/SwaggerPluginsSupport.groovy b/springfox-swagger-common/src/test/groovy/springfox/documentation/swagger/mixins/SwaggerPluginsSupport.groovy
@@ -64,6 +64,7 @@ class SwaggerPluginsSupport {
                                        new ParameterNameReader()])
     plugins.operationBuilderPlugins = create([])
     plugins.resourceGroupingStrategies = create([new ClassOrApiAnnotationResourceGrouping()])
+    plugins.apiListingScanners = create([])
     plugins.operationModelsProviders = create([
         new OperationModelsProvider(resolver),
         new SwaggerOperationModelsProvider(resolver)])

Original file line number	Diff line number	Diff line change
`@@ -55,8 +55,6 @@ public ApiDescriptionReader(`
`55`	`55`	`}`
`56`	`56`
`57`	`57`	`public List<ApiDescription> read(RequestMappingContext outerContext) {`
`58`		`-// RequestMappingInfo requestMappingInfo = outerContext.getRequestMappingInfo();`
`59`		`-// HandlerMethod handlerMethod = outerContext.getHandlerMethod();`
`60`	`58`	`PatternsRequestCondition patternsCondition = outerContext.getPatternsCondition();`
`61`	`59`	`ApiSelector selector = outerContext.getDocumentationContext().getApiSelector();`
`62`	`60`
Original file line number	Diff line number	Diff line change
`@@ -88,7 +88,7 @@ public Multimap<String, ApiListing> scan(ApiListingScanningContext context) {`
`88`	`88`	`models.putAll(apiModelReader.read(each.withKnownModels(models)));`
`89`	`89`	`apiDescriptions.addAll(apiDescriptionReader.read(each));`
`90`	`90`	`}`
`91`		`-`
	`91`	`+ apiDescriptions.addAll(pluginsManager.additionalListings(context));`
`92`	`92`
`93`	`93`	`List<ApiDescription> sortedApis = newArrayList(apiDescriptions);`
`94`	`94`	`Collections.sort(sortedApis, documentationContext.getApiDescriptionOrdering());`