com.mangofactory.swagger.plugin
Class SwaggerSpringMvcPlugin

java.lang.Object
  com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin

public class SwaggerSpringMvcPlugin
extends java.lang.Object

A builder which is intended to be the primary interface into the swagger-springmvc framework. Provides sensible defaults and convenience methods for configuration.

Constructor Summary

SwaggerSpringMvcPlugin(SpringSwaggerConfig springSwaggerConfig)
Default constructor.

Method Summary

SwaggerSpringMvcPlugin	alternateTypeProvider(com.mangofactory.swagger.models.alternates.AlternateTypeProvider alternateTypeProvider) Overrides the default AlternateTypeProvider.
SwaggerSpringMvcPlugin	alternateTypeRules(com.mangofactory.swagger.models.alternates.AlternateTypeRule... alternateTypeRules) Adds model substitution rules (alternateTypeRules)
SwaggerSpringMvcPlugin	apiDescriptionOrdering(com.google.common.collect.Ordering<com.mangofactory.swagger.models.dto.ApiDescription> apiDescriptionOrdering) Controls how com.wordnik.swagger.model.ApiDescription's are ordered.
SwaggerSpringMvcPlugin	apiInfo(com.mangofactory.swagger.models.dto.ApiInfo apiInfo) Sets the api's meta information as included in the json ResourceListing response.
SwaggerSpringMvcPlugin	apiListingReferenceOrdering(com.google.common.collect.Ordering<com.mangofactory.swagger.models.dto.ApiListingReference> apiListingReferenceOrdering) Controls how ApiListingReference's are sorted.
SwaggerSpringMvcPlugin	apiVersion(java.lang.String apiVersion) Sets the api version.
SwaggerSpringMvcPlugin	authorizationContext(AuthorizationContext authorizationContext) Configures which api operations (via regex patterns) and HTTP methods to apply swagger authorization to.
SwaggerSpringMvcPlugin	authorizationTypes(java.util.List<com.mangofactory.swagger.models.dto.AuthorizationType> authorizationTypes) Configures the global com.wordnik.swagger.model.AuthorizationType's applicable to all or some of the api operations.
SwaggerSpringMvcPlugin	build() Builds the SwaggerSpringMvcPlugin by merging/overlaying user specified values.
SwaggerSpringMvcPlugin	customAnnotationReaders(java.util.Collection<RequestMappingReader> customAnnotationReaders) Hook for adding custom annotations readers.
SwaggerSpringMvcPlugin	directModelSubstitute(java.lang.Class clazz, java.lang.Class with) Directly substitutes a model class with the supplied substitute e.g directModelSubstitute(LocalDate.class, Date.class) would substitute LocalDate with Date
SwaggerSpringMvcPlugin	enable(boolean externallyConfiguredFlag) Hook to externally control auto initialization of this swagger plugin instance.
SwaggerSpringMvcPlugin	excludeAnnotations(java.lang.Class<? extends java.lang.annotation.Annotation>... excludeAnnotations) Spring controllers or request mappings with these annotations will be excluded from the generated swagger JSON.
SwaggerSpringMvcPlugin	genericModelSubstitutes(java.lang.Class... genericClasses) Substitutes each generic class with it's direct parameterized type.
SwaggerSpringMvcPlugin	genericTypeNamingStrategy(com.mangofactory.swagger.models.GenericTypeNamingStrategy strategy) Controls how generics are encoded as swagger types, specifically around the characters used to open, close, and delimit lists of types.
SwaggerSpringMvcPlugin	globalResponseMessage(org.springframework.web.bind.annotation.RequestMethod requestMethod, java.util.List<com.mangofactory.swagger.models.dto.ResponseMessage> responseMessages) Overrides the default http response messages at the http request method level.
SwaggerSpringMvcPlugin	ignoredParameterTypes(java.lang.Class... classes) Adds ignored controller method parameter types so that the framework does not generate swagger model or parameter information for these specific types.
SwaggerSpringMvcPlugin	includePatterns(java.lang.String... includePatterns) Controls which controllers, more specifically, which Spring RequestMappings to include in the swagger Resource Listing.
protected void	initialize() Called by the framework hence protected
boolean	isEnabled()
SwaggerSpringMvcPlugin	modelProvider(com.mangofactory.swagger.models.ModelProvider modelProvider) Overrides the default com.mangofactory.swagger.models.ModelProvider
SwaggerSpringMvcPlugin	pathProvider(SwaggerPathProvider swaggerPathProvider) Determines the generated, swagger specific, urls.
SwaggerSpringMvcPlugin	requestMappingPatternMatcher(RequestMappingPatternMatcher requestMappingPatternMatcher) Hook for adding custom annotations readers.
SwaggerSpringMvcPlugin	resourceGroupingStrategy(ResourceGroupingStrategy resourceGroupingStrategy) Controls which ResourceListing's, RequestMappings belong to.
SwaggerSpringMvcPlugin	swaggerGroup(java.lang.String swaggerGroup) If more than one instance of SwaggerSpringMvcPlugin exists, each one must have a unique swaggerGroup as supplied by this method.
SwaggerSpringMvcPlugin	useDefaultResponseMessages(boolean apply) Allows ignoring predefined response message defaults

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SwaggerSpringMvcPlugin

public SwaggerSpringMvcPlugin(SpringSwaggerConfig springSwaggerConfig)

Default constructor. The argument springSwaggerConfig is used to by this class to establish sensible defaults.

Parameters:

springSwaggerConfig -

Method Detail

apiInfo

public SwaggerSpringMvcPlugin apiInfo(com.mangofactory.swagger.models.dto.ApiInfo apiInfo)

Sets the api's meta information as included in the json ResourceListing response.

Parameters:

apiInfo -

Returns:

this SwaggerSpringMvcPlugin

authorizationTypes

public SwaggerSpringMvcPlugin authorizationTypes(java.util.List<com.mangofactory.swagger.models.dto.AuthorizationType> authorizationTypes)

Configures the global com.wordnik.swagger.model.AuthorizationType's applicable to all or some of the api operations. The configuration of which operations have associated AuthorizationTypes is configured with com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin#authorizationContext

Parameters:

authorizationTypes - a list of global AuthorizationType's

Returns:

this SwaggerSpringMvcPlugin

authorizationContext

public SwaggerSpringMvcPlugin authorizationContext(AuthorizationContext authorizationContext)

Configures which api operations (via regex patterns) and HTTP methods to apply swagger authorization to.

Parameters:

authorizationContext -

Returns:

this SwaggerSpringMvcPlugin

swaggerGroup

public SwaggerSpringMvcPlugin swaggerGroup(java.lang.String swaggerGroup)

If more than one instance of SwaggerSpringMvcPlugin exists, each one must have a unique swaggerGroup as supplied by this method. Defaults to "default".

Parameters:

swaggerGroup - - the unique identifier of this swagger group/configuration

Returns:

this SwaggerSpringMvcPlugin

pathProvider

public SwaggerSpringMvcPlugin pathProvider(SwaggerPathProvider swaggerPathProvider)

Determines the generated, swagger specific, urls. By default, relative urls are generated. If absolute urls are required, supply an implementation of AbsoluteSwaggerPathProvider

Parameters:

swaggerPathProvider -

Returns:

this SwaggerSpringMvcPlugin

See Also:

SwaggerPathProvider

excludeAnnotations

public SwaggerSpringMvcPlugin excludeAnnotations(java.lang.Class<? extends java.lang.annotation.Annotation>... excludeAnnotations)

Spring controllers or request mappings with these annotations will be excluded from the generated swagger JSON.

Parameters:

excludeAnnotations - one or more java Annotation classes

Returns:

this SwaggerSpringMvcPlugin

includePatterns

public SwaggerSpringMvcPlugin includePatterns(java.lang.String... includePatterns)

Controls which controllers, more specifically, which Spring RequestMappings to include in the swagger Resource Listing. Under the hood, com.mangofactory.swagger.scanners.RequestMappingPatternMatcheris used to match a given org.springframework.web.servlet.mvc.condition.PatternsRequestCondition against the includePatterns supplied here. RegexRequestMappingPatternMatcher is the default implementation and requires these includePatterns are valid regular expressions. If not supplied a single pattern ".*?" is used which matches anything and hence all RequestMappings.

Parameters:

includePatterns - - the regular expressions to determine which Spring RequestMappings to include.

Returns:

this SwaggerSpringMvcPlugin

globalResponseMessage

public SwaggerSpringMvcPlugin globalResponseMessage(org.springframework.web.bind.annotation.RequestMethod requestMethod,
                                                    java.util.List<com.mangofactory.swagger.models.dto.ResponseMessage> responseMessages)

Overrides the default http response messages at the http request method level. To set specific response messages for specific api operations use the swagger core annotations on the appropriate controller methods.

Parameters:

requestMethod - - http request method for which to apply the message

responseMessages - - the message

Returns:

this SwaggerSpringMvcPlugin

See Also:

and, ApiResponses, SpringSwaggerConfig.defaultResponseMessages()

ignoredParameterTypes

public SwaggerSpringMvcPlugin ignoredParameterTypes(java.lang.Class... classes)

Adds ignored controller method parameter types so that the framework does not generate swagger model or parameter information for these specific types. e.g. HttpServletRequest/HttpServletResponse which are already included in the pre-configured ignored types.

Parameters:

classes - the classes to ignore

Returns:

this SwaggerSpringMvcPlugin

See Also:

SpringSwaggerConfig.defaultIgnorableParameterTypes()

alternateTypeProvider

public SwaggerSpringMvcPlugin alternateTypeProvider(com.mangofactory.swagger.models.alternates.AlternateTypeProvider alternateTypeProvider)

Overrides the default AlternateTypeProvider.

Parameters:

alternateTypeProvider -

Returns:

this SwaggerSpringMvcPlugin

apiVersion

public SwaggerSpringMvcPlugin apiVersion(java.lang.String apiVersion)

Sets the api version. The 'apiVersion' on the swagger Resource Listing

Parameters:

apiVersion -

Returns:

this SwaggerSpringMvcPlugin

modelProvider

public SwaggerSpringMvcPlugin modelProvider(com.mangofactory.swagger.models.ModelProvider modelProvider)

Overrides the default com.mangofactory.swagger.models.ModelProvider

Parameters:

modelProvider -

Returns:

this SwaggerSpringMvcPlugin

alternateTypeRules

public SwaggerSpringMvcPlugin alternateTypeRules(com.mangofactory.swagger.models.alternates.AlternateTypeRule... alternateTypeRules)

Adds model substitution rules (alternateTypeRules)

Parameters:

alternateTypeRules -

Returns:

this SwaggerSpringMvcPlugin

See Also:

Alternates.newRule(java.lang.reflect.Type, java.lang.reflect.Type)

directModelSubstitute

public SwaggerSpringMvcPlugin directModelSubstitute(java.lang.Class clazz,
                                                    java.lang.Class with)

Directly substitutes a model class with the supplied substitute e.g directModelSubstitute(LocalDate.class, Date.class) would substitute LocalDate with Date

Parameters:

clazz - class to substitute

with - the class which substitutes 'clazz'

Returns:

this SwaggerSpringMvcPlugin

useDefaultResponseMessages

public SwaggerSpringMvcPlugin useDefaultResponseMessages(boolean apply)

Allows ignoring predefined response message defaults

Parameters:

apply - flag to determine if the default response messages are used true - the default response messages are added to the global response messages false - the default response messages are added to the global response messages

Returns:

this SwaggerSpringMvcPlugin

genericModelSubstitutes

public SwaggerSpringMvcPlugin genericModelSubstitutes(java.lang.Class... genericClasses)

Substitutes each generic class with it's direct parameterized type. e.g. .genericModelSubstitutes(ResponseEntity.class) would substitute ResponseEntity <MyModel> with MyModel

Parameters:

genericClasses - - generic classes on which to apply generic model substitution.

Returns:

this SwaggerSpringMvcPlugin

genericTypeNamingStrategy

public SwaggerSpringMvcPlugin genericTypeNamingStrategy(com.mangofactory.swagger.models.GenericTypeNamingStrategy strategy)

Controls how generics are encoded as swagger types, specifically around the characters used to open, close, and delimit lists of types.

Parameters:

strategy - a GenericTypeNamingStrategy implementation, defaults to DefaultGenericTypeNamingStrategy

Returns:

this SwaggerSpringMvcPlugin

apiListingReferenceOrdering

public SwaggerSpringMvcPlugin apiListingReferenceOrdering(com.google.common.collect.Ordering<com.mangofactory.swagger.models.dto.ApiListingReference> apiListingReferenceOrdering)

Controls how ApiListingReference's are sorted. i.e the ordering of the api's within the swagger Resource Listing. The default sort is Lexicographically by the ApiListingReference's path

Parameters:

apiListingReferenceOrdering -

Returns:

this SwaggerSpringMvcPlugin

apiDescriptionOrdering

public SwaggerSpringMvcPlugin apiDescriptionOrdering(com.google.common.collect.Ordering<com.mangofactory.swagger.models.dto.ApiDescription> apiDescriptionOrdering)

Controls how com.wordnik.swagger.model.ApiDescription's are ordered. The default sort is Lexicographically by the ApiDescription's path.

Parameters:

apiDescriptionOrdering -

Returns:

this SwaggerSpringMvcPlugin

See Also:

ApiListingScanner

resourceGroupingStrategy

public SwaggerSpringMvcPlugin resourceGroupingStrategy(ResourceGroupingStrategy resourceGroupingStrategy)

Controls which ResourceListing's, RequestMappings belong to.

Parameters:

resourceGroupingStrategy -

Returns:

this SwaggerSpringMvcPlugin

See Also:

ApiListingReferenceScanner.scanSpringRequestMappings()

customAnnotationReaders

public SwaggerSpringMvcPlugin customAnnotationReaders(java.util.Collection<RequestMappingReader> customAnnotationReaders)

Hook for adding custom annotations readers. Useful when you want to add your own annotation to be mapped to swagger model.

Parameters:

customAnnotationReaders - list of RequestMappingReader

Returns:

this SwaggerSpringMvcPlugin

requestMappingPatternMatcher

public SwaggerSpringMvcPlugin requestMappingPatternMatcher(RequestMappingPatternMatcher requestMappingPatternMatcher)

Hook for adding custom annotations readers. Useful when you want to add your own annotation to be mapped to swagger model.

Parameters:

requestMappingPatternMatcher - an implementation of .RequestMappingPatternMatcher. Out of the box the library comes with RegexRequestMappingPatternMatcher and AntRequestMappingPatternMatcher

Returns:

this SwaggerSpringMvcPlugin

enable

public SwaggerSpringMvcPlugin enable(boolean externallyConfiguredFlag)

Hook to externally control auto initialization of this swagger plugin instance. Typically used if defer initialization.

Parameters:

externallyConfiguredFlag - - true to turn it on, false to turn it off

Returns:

this SwaggerSpringMvcPlugin

initialize

protected void initialize()

Called by the framework hence protected

build

public SwaggerSpringMvcPlugin build()

Builds the SwaggerSpringMvcPlugin by merging/overlaying user specified values. It is not necessary to call this method when defined as a spring bean. NOTE: Calling this method more than once has no effect.

Returns:

this SwaggerSpringMvcPlugin

See Also:

SwaggerPluginAdapter

isEnabled

public boolean isEnabled()