springfox.documentation.spring.web.plugins

Class Docket

java.lang.Object

springfox.documentation.spring.web.plugins.Docket

All Implemented Interfaces:

org.springframework.plugin.core.Plugin<DocumentationType>, DocumentationPlugin

public class Docket
extends java.lang.Object
implements DocumentationPlugin

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

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	DEFAULT_GROUP_NAME

Constructor Summary

Constructors

Constructor and Description
Docket(DocumentationType documentationType)

Method Summary

Methods

Modifier and Type	Method and Description
Docket	additionalModels(com.fasterxml.classmate.ResolvedType first, com.fasterxml.classmate.ResolvedType... remaining) Method to add additional models that are not part of any annotation or are perhaps implicit
Docket	alternateTypeRules(AlternateTypeRule... alternateTypeRules) Adds model substitution rules (alternateTypeRules)
Docket	apiDescriptionOrdering(com.google.common.collect.Ordering<ApiDescription> apiDescriptionOrdering) Controls how com.wordnik.swagger.model.ApiDescription's are ordered.
Docket	apiInfo(ApiInfo apiInfo) Sets the api's meta information as included in the json ResourceListing response.
Docket	apiListingReferenceOrdering(com.google.common.collect.Ordering<ApiListingReference> apiListingReferenceOrdering) Controls how ApiListingReference's are sorted.
DocumentationContext	configure(DocumentationContextBuilder builder) Builds the Docket by merging/overlaying user specified values.
Docket	consumes(java.util.Set<java.lang.String> consumes)
Docket	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
Docket	enable(boolean externallyConfiguredFlag) Hook to externally control auto initialization of this swagger plugin instance.
Docket	enableUrlTemplating(boolean enabled) Decides whether to use url templating for paths.
Docket	extensions(java.util.List<VendorExtension> vendorExtensions) Add to the api's vendor extensions
Docket	forCodeGeneration(boolean forCodeGen) Set this to true in order to make the documentation code generation friendly
Docket	genericModelSubstitutes(java.lang.Class... genericClasses) Substitutes each generic class with it's direct parameterized type.
DocumentationType	getDocumentationType()
java.lang.String	getGroupName() Gets the group name for the plugin.
Docket	globalOperationParameters(java.util.List<Parameter> operationParameters) Adds default parameters which will be applied to all operations.
Docket	globalResponseMessage(org.springframework.web.bind.annotation.RequestMethod requestMethod, java.util.List<ResponseMessage> responseMessages) Overrides the default http response messages at the http request method level.
Docket	groupName(java.lang.String groupName) If more than one instance of Docket exists, each one must have a unique groupName as supplied by this method.
Docket	host(java.lang.String host)
Docket	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.
boolean	isEnabled()
Docket	operationOrdering(com.google.common.collect.Ordering<Operation> operationOrdering) Provide an ordering schema for operations NOTE: @see #732 in case you're wondering why specifying position might not work.
Docket	pathMapping(java.lang.String path) Extensibility mechanism to add a servlet path mapping, if there is one, to the apis base path.
Docket	pathProvider(PathProvider pathProvider) Determines the generated, swagger specific, urls.
Docket	produces(java.util.Set<java.lang.String> produces)
Docket	protocols(java.util.Set<java.lang.String> protocols)
Docket	securityContexts(java.util.List<SecurityContext> securityContexts) Configures which api operations (via regex patterns) and HTTP methods to apply security contexts to apis.
Docket	securitySchemes(java.util.List<? extends SecurityScheme> securitySchemes) Configures the global com.wordnik.swagger.model.SecurityScheme's applicable to all or some of the api operations.
ApiSelectorBuilder	select() Initiates a builder for api selection.
boolean	supports(DocumentationType delimiter)
Docket	tags(Tag first, Tag... remaining) Method to add global tags to the docket
Docket	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

Field Detail

DEFAULT_GROUP_NAME

public static final java.lang.String DEFAULT_GROUP_NAME

See Also:

Constant Field Values

Constructor Detail

Docket

public Docket(DocumentationType documentationType)

Method Detail

extensions

public Docket extensions(java.util.List<VendorExtension> vendorExtensions)

Add to the api's vendor extensions

Parameters:

vendorExtensions - Indicates the vendor extension information

Returns:

this Docket

apiInfo

public Docket apiInfo(ApiInfo apiInfo)

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

Parameters:

apiInfo - Indicates the api information

Returns:

this Docket

securitySchemes

public Docket securitySchemes(java.util.List<? extends SecurityScheme> securitySchemes)

Configures the global com.wordnik.swagger.model.SecurityScheme's applicable to all or some of the api operations. The configuration of which operations have associated SecuritySchemes is configured with springfox.swagger.plugins.Docket#securityContexts

Parameters:

securitySchemes - a list of security schemes

Returns:

this Docket

securityContexts

public Docket securityContexts(java.util.List<SecurityContext> securityContexts)

Configures which api operations (via regex patterns) and HTTP methods to apply security contexts to apis.

Parameters:

securityContexts - - defines security requirements for the apis

Returns:

this Docket

groupName

public Docket groupName(java.lang.String groupName)

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

Parameters:

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

Returns:

this Docket

pathProvider

public Docket pathProvider(PathProvider pathProvider)

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

Parameters:

pathProvider -

Returns:

this Docket

See Also:

AbstractPathProvider

globalResponseMessage

public Docket globalResponseMessage(org.springframework.web.bind.annotation.RequestMethod requestMethod,
                           java.util.List<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 Docket

See Also:

and, ApiResponses, Defaults.defaultResponseMessages()

globalOperationParameters

public Docket globalOperationParameters(java.util.List<Parameter> operationParameters)

Adds default parameters which will be applied to all operations.

Parameters:

operationParameters - parameters which will be globally applied to all operations

Returns:

this Docket

ignoredParameterTypes

public Docket 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 Docket

See Also:

Defaults.defaultIgnorableParameterTypes()

produces

public Docket produces(java.util.Set<java.lang.String> produces)

consumes

public Docket consumes(java.util.Set<java.lang.String> consumes)

host

public Docket host(java.lang.String host)

protocols

public Docket protocols(java.util.Set<java.lang.String> protocols)

alternateTypeRules

public Docket alternateTypeRules(AlternateTypeRule... alternateTypeRules)

Adds model substitution rules (alternateTypeRules)

Parameters:

alternateTypeRules -

Returns:

this Docket

See Also:

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

operationOrdering

public Docket operationOrdering(com.google.common.collect.Ordering<Operation> operationOrdering)

Provide an ordering schema for operations NOTE: @see #732 in case you're wondering why specifying position might not work.

Parameters:

operationOrdering -

Returns:

directModelSubstitute

public Docket 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 Docket

genericModelSubstitutes

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

Substitutes each generic class with it's direct parameterized type. Use this method to only for types with a single parameterized type. e.g. List<T> or ResponseEntity<T> .genericModelSubstitutes(ResponseEntity.class) would substitute ResponseEntity <MyModel> with MyModel

Parameters:

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

Returns:

this Docket

useDefaultResponseMessages

public Docket 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 not added to the global response messages

Returns:

this Docket

apiListingReferenceOrdering

public Docket apiListingReferenceOrdering(com.google.common.collect.Ordering<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 NOTE: @see #732 in case you're wondering why specifying position might not work.

Parameters:

apiListingReferenceOrdering -

Returns:

this Docket

apiDescriptionOrdering

public Docket apiDescriptionOrdering(com.google.common.collect.Ordering<ApiDescription> apiDescriptionOrdering)

Controls how com.wordnik.swagger.model.ApiDescription's are ordered. The default sort is Lexicographically by the ApiDescription's path. NOTE: @see #732 in case you're wondering why specifying position might not work.

Parameters:

apiDescriptionOrdering -

Returns:

this Docket

See Also:

ApiListingScanner

enable

public Docket 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 Docket

forCodeGeneration

public Docket forCodeGeneration(boolean forCodeGen)

Set this to true in order to make the documentation code generation friendly

Parameters:

forCodeGen - - true|false determines the naming strategy used

Returns:

this Docket

pathMapping

public Docket pathMapping(java.lang.String path)

Extensibility mechanism to add a servlet path mapping, if there is one, to the apis base path.

Parameters:

path - - path that acts as a prefix to the api base path

Returns:

this Docket

enableUrlTemplating

public Docket enableUrlTemplating(boolean enabled)

Decides whether to use url templating for paths. This is especially useful when you have search api's that might have multiple request mappings for each search use case. This is an incubating feature that may not continue to be supported after the swagger specification is modified to accomodate the usecase as described in issue #711

Parameters:

enabled -

Returns:

additionalModels

public Docket additionalModels(com.fasterxml.classmate.ResolvedType first,
                      com.fasterxml.classmate.ResolvedType... remaining)

Method to add additional models that are not part of any annotation or are perhaps implicit

Parameters:

first - - at least one is required

remaining - - possible collection of more

Returns:

on-going docket

Since:

2.4.0

tags

public Docket tags(Tag first,
          Tag... remaining)

Method to add global tags to the docket

Parameters:

first - - atleast one tag is required to use this method

remaining - - remaining tags

Returns:

select

public ApiSelectorBuilder select()

Initiates a builder for api selection.

Returns:

api selection builder. To complete building the api selector, the build method of the api selector needs to be called, this will automatically fall back to building the docket when the build method is called.

configure

public DocumentationContext configure(DocumentationContextBuilder builder)

Builds the Docket 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.

Specified by:

configure in interface DocumentationPlugin

Parameters:

builder - - @see springfox.documentation.spi.service.contexts.DocumentationContextBuilder

Returns:

context to use for building the documentation

See Also:

DocumentationPluginsBootstrapper

getGroupName

public java.lang.String getGroupName()

Description copied from interface: DocumentationPlugin

Gets the group name for the plugin. This is expected to be unique for each instance of the plugin

Specified by:

getGroupName in interface DocumentationPlugin

Returns:

group the plugin belongs to

isEnabled

public boolean isEnabled()

Specified by:

isEnabled in interface DocumentationPlugin

Returns:

indicator to determine if the plugin is enabled

getDocumentationType

public DocumentationType getDocumentationType()

Specified by:

getDocumentationType in interface DocumentationPlugin

supports

public boolean supports(DocumentationType delimiter)

Specified by:

supports in interface org.springframework.plugin.core.Plugin<DocumentationType>