Package springfox.documentation.spring.web.plugins

Class 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 Springfox framework. Provides sensible defaults and convenience methods for configuration.

    • Field Detail

      • DEFAULT_GROUP_NAME

        public static final java.lang.String DEFAULT_GROUP_NAME
        See Also:
        Constant Field Values

    • 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<SecurityScheme> securitySchemes)
        Configures the global io.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 - - provides an alternate implementation of path provider
        Returns:
        this Docket
        See Also:
        DefaultPathProvider

      • globalResponseMessage

        @Deprecated
public Docket globalResponseMessage​(org.springframework.web.bind.annotation.RequestMethod requestMethod,
                                    java.util.List<ResponseMessage> responseMessages)
        Deprecated.
        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 swagger annotations <code>@ApiResponse</code>, <code>@ApiResponses</code> .
        Since:
        3.0.0
        See Also:
        Use instead

      • globalResponses

        public Docket globalResponses​(org.springframework.http.HttpMethod httpMethod,
                              java.util.List<Response> responses)
        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:
        httpMethod - - http request method for which to apply the message
        responses - - the message
        Returns:
        this Docket See swagger annotations <code>@ApiResponse</code>, <code>@ApiResponses</code> .
        See Also:
        Defaults.defaultResponseMessages()

      • globalOperationParameters

        @Deprecated
public Docket globalOperationParameters​(java.util.List<Parameter> operationParameters)
        Deprecated.
        Adds default parameters which will be applied to all operations.
        Parameters:
        operationParameters - parameters which will be globally applied to all operations
        Returns:
        this Docket use @see globalRequestParameters instead

      • globalRequestParameters

        public Docket globalRequestParameters​(java.util.List<RequestParameter> globalRequestParameters)
        Adds default parameters which will be applied to all operations.
        Parameters:
        globalRequestParameters - 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)

      • operationOrdering

        public Docket operationOrdering​(java.util.Comparator<Operation> operationOrdering)
        Provide an ordering schema for operations

        NOTE: @see #732 in case you're wondering why specifying position might not work.

        Parameters:
        operationOrdering - - ordering of the operations
        Returns:
        this Docket

      • 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​(java.util.Comparator<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 - - ordering of the api listing references
        Returns:
        this Docket

      • apiDescriptionOrdering

        public Docket apiDescriptionOrdering​(java.util.Comparator<ApiDescription> apiDescriptionOrdering)
        Controls how io.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 - - ordering of the api descriptions
        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 accommodate the use case as described in issue #711

        Parameters:
        enabled - - when true it enables rfc6570 url templates
        Returns:
        this Docket

      • 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 - - at least one tag is required to use this method
        remaining - - remaining tags
        Returns:
        this Docket

      • servers

        public Docket servers​(Server first,
                      Server... remaining)
        Method to add global tags to the docket
        Parameters:
        first - - at least one tag is required to use this method
        remaining - - remaining tags
        Returns:
        this Docket

      • 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