<commit_before>== Configuring Springfox

:releaseVersion: {springfox-released-version}
:snapshotVersion: {springfox-current-version}

To enable support for swagger specification 1.2 use the ```@EnableSwagger``` annotation

To enable support for swagger specification 2.0 use the ```@EnableSwagger2``` annotation

To document the service we use a ```Docket```. This is changed to be more inline with the fact that expressing the
contents of the documentation is agnostic of the format the documentation is rendered.

Docket https://www.wordnik.com/words/docket[stands for] *A summary or other brief statement of the contents of a
document; an abstract.*

`Docket` helps configure a  subset of the services to be documented and groups them by name. Significant changes
to this is the ability to provide an expressive predicate based for api selection.

```java
  import static springfox.documentation.builders.PathSelectors.*;
  import static com.google.common.base.Predicates.*;

  @Bean
  public Docket swaggerSpringMvcPlugin() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("business-api")
            .select()
               //Ignores controllers annotated with @CustomIgnore
              .apis(not(withClassAnnotation(CustomIgnore.class)) //Selection by RequestHandler
              .paths(paths()) // and by paths
              .build()
            .apiInfo(apiInfo())
            .securitySchemes(securitySchemes())
            .securityContext(securityContext());
  }

  //Here is an example where we select any api that matches one of these paths
  private Predicate<String> paths() {
    return or(
        regex("/business.*"),
        regex("/some.*"),
        regex("/contacts.*"),
        regex("/pet.*"),
        regex("/springsRestController.*"),
        regex("/test.*"));
  }

```

For a list of handy predicates Look at https://github.com/springfox/springfox/blob/master/springfox-core/src/main/java/springfox/documentation/builders/RequestHandlerSelectors.java[RequestHandlerSelectors]
and https://github.com/springfox/springfox/blob/master/springfox-core/src/main/java/springfox/documentation/builders/PathSelectors.java[PathSelectors].

=== Configuring the ObjectMapper

A simple way to configure the object mapper is to listen for the ```ObjectMapperConfigured``` event. Regardless of
whether there is a customized ObjectMapper in play with a corresponding MappingJackson2HttpMessageConverter, the
library always has a configured ObjectMapper that is customized to serialize swagger 1.2 and swagger 2.0 types.

In order to do this implement the ```ApplicationListener<ObjectMapperConfigured>``` interface. The event has a handle
 to the ObjectMapper that was configured. Configuring application specific ObjectMapper customizations in this
 applicaiton event handler guarantees that application specific  customizations will be applied to each and every
 ObjectMapper that is in play.

If you encounter a NullPointerException during application startup like https://github.com/springfox/springfox/issues/635[this issue]. Its because most likely the ```WebMvcConfigurerAdapter``` isn't working.
These adapter especially in a non-spring-boot scenarios will only get loaded if the @EnableWebMvc
http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/servlet/config/annotation/WebMvcConfigurer.html[annotation is present].

If using Spring Boot Web MVC, there is no need to use the @EnableWebMvc annotation, as the framework automatically detects Web MVC usage and configures itself as appropriate.
In this scenario, Springfox will not correctly generate and expose the Swagger UI endpoint (`/swagger-ui.html`) if @EnableWebMvc is present in the application.

Caveat to using the library is that it depends on Jackson for serialization, more importantly the `ObjectMapper`. A
good example of where this breaks down is the following http://stackoverflow.com/a/30220562/19219[issue when using Gson serialization]

=== Customizing the swagger endpoints.

By default the swagger service descriptions are generated at the following urls

[options="header,footer"]
|=======================
|Swagger version  | Documentation Url           | Group
|1.2              | /api-docs                   | implicit *default* group
|2.0              | /api-docs?group=external    | *external* group via docket.groupName()
|2.0              | /v2/api-docs                | implicit *default* group
|2.0              | /v2/api-docs?group=external | *external* group via docket.groupName()
|=======================

To customize these endpoints, loading a http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/context/annotation/PropertySource.html[property source] with the following properties
allows the properties to be  overridden

[options="header,footer"]
|=======================
|Swagger version | Override property
|1.2             | springfox.documentation.swagger.v1.path
|2.0             | springfox.documentation.swagger.v2.path
|=======================

=== Overriding property datatypes

Using the ```ApiModelProperty#dataType``` we can override the inferred data types. However it is restricted
 to only allow data types to be specified with a fully qualified class name. For e.g. if we have the following
 definition

```java

// if com.qualified.ReplaceWith is not a Class that can be created using Class.forName(...)
// Original will be replaced with the new class
@ApiModelProperty(dataType = "com.qualified.ReplacedWith")
public Original getOriginal() { ... }

// if ReplaceWith is not a Class that can be created using Class.forName(...) Original will be preserved
@ApiModelProperty(dataType = "ReplaceWith")
public Original getAnotherOriginal() { ... }
```

=== Docket XML Configuration

To use the plugin you must create a spring java configuration class which uses spring's `@Configuration`.
This config class must then be defined in your xml application context.


```xml
<!-- Required so springfox can access spring's RequestMappingHandlerMapping  -->
<mvc:annotation-driven/>

<!-- Required to enable Spring post processing on @Configuration classes. -->
<context:annotation-config/>

<bean class="com.yourapp.configuration.MySwaggerConfig"/>
```

```java

@Configuration
@EnableSwagger //Loads the spring beans required by the framework
public class MySwaggerConfig {

   /**
    * Every Docket bean is picked up by the swagger-mvc framework - allowing for multiple
    * swagger groups i.e. same code base multiple swagger resource listings.
    */
   @Bean
   public Docket customDocket(){
      return new Docket(); //some customization goes here
   }

}
```


=== Docket Spring Java Configuration

- Use the `@EnableSwagger` or `@EnableSwagger2` annotation.
- Define one or more Docket instances using springs `@Bean` annotation.

```java
@Configuration
@EnableWebMvc //NOTE: Only needed in a non-springboot application
@EnableSwagger2
@ComponentScan("com.myapp.controllers")
public class CustomJavaPluginConfig {


   @Bean //Don't forget the @Bean annotation
   public Docket customImplementation(){
      return new Docket()
            .apiInfo(apiInfo())
            .includePatterns(".*pet.*");
   }<commit_msg>Fixes inacurate documentation regarding includePatterns<commit_after>== Configuring Springfox

:releaseVersion: {springfox-released-version}
:snapshotVersion: {springfox-current-version}

To enable support for swagger specification 1.2 use the ```@EnableSwagger``` annotation

To enable support for swagger specification 2.0 use the ```@EnableSwagger2``` annotation

To document the service we use a ```Docket```. This is changed to be more inline with the fact that expressing the
contents of the documentation is agnostic of the format the documentation is rendered.

Docket https://www.wordnik.com/words/docket[stands for] *A summary or other brief statement of the contents of a
document; an abstract.*

`Docket` helps configure a  subset of the services to be documented and groups them by name. Significant changes
to this is the ability to provide an expressive predicate based for api selection.

```java
  import static springfox.documentation.builders.PathSelectors.*;
  import static com.google.common.base.Predicates.*;

  @Bean
  public Docket swaggerSpringMvcPlugin() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("business-api")
            .select()
               //Ignores controllers annotated with @CustomIgnore
              .apis(not(withClassAnnotation(CustomIgnore.class)) //Selection by RequestHandler
              .paths(paths()) // and by paths
              .build()
            .apiInfo(apiInfo())
            .securitySchemes(securitySchemes())
            .securityContext(securityContext());
  }

  //Here is an example where we select any api that matches one of these paths
  private Predicate<String> paths() {
    return or(
        regex("/business.*"),
        regex("/some.*"),
        regex("/contacts.*"),
        regex("/pet.*"),
        regex("/springsRestController.*"),
        regex("/test.*"));
  }

```

For a list of handy predicates Look at https://github.com/springfox/springfox/blob/master/springfox-core/src/main/java/springfox/documentation/builders/RequestHandlerSelectors.java[RequestHandlerSelectors]
and https://github.com/springfox/springfox/blob/master/springfox-core/src/main/java/springfox/documentation/builders/PathSelectors.java[PathSelectors].

=== Configuring the ObjectMapper

A simple way to configure the object mapper is to listen for the ```ObjectMapperConfigured``` event. Regardless of
whether there is a customized ObjectMapper in play with a corresponding MappingJackson2HttpMessageConverter, the
library always has a configured ObjectMapper that is customized to serialize swagger 1.2 and swagger 2.0 types.

In order to do this implement the ```ApplicationListener<ObjectMapperConfigured>``` interface. The event has a handle
 to the ObjectMapper that was configured. Configuring application specific ObjectMapper customizations in this
 applicaiton event handler guarantees that application specific  customizations will be applied to each and every
 ObjectMapper that is in play.

If you encounter a NullPointerException during application startup like https://github.com/springfox/springfox/issues/635[this issue]. Its because most likely the ```WebMvcConfigurerAdapter``` isn't working.
These adapter especially in a non-spring-boot scenarios will only get loaded if the @EnableWebMvc
http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/servlet/config/annotation/WebMvcConfigurer.html[annotation is present].

If using Spring Boot Web MVC, there is no need to use the @EnableWebMvc annotation, as the framework automatically detects Web MVC usage and configures itself as appropriate.
In this scenario, Springfox will not correctly generate and expose the Swagger UI endpoint (`/swagger-ui.html`) if @EnableWebMvc is present in the application.

Caveat to using the library is that it depends on Jackson for serialization, more importantly the `ObjectMapper`. A
good example of where this breaks down is the following http://stackoverflow.com/a/30220562/19219[issue when using Gson serialization]

=== Customizing the swagger endpoints.

By default the swagger service descriptions are generated at the following urls

[options="header,footer"]
|=======================
|Swagger version  | Documentation Url           | Group
|1.2              | /api-docs                   | implicit *default* group
|2.0              | /api-docs?group=external    | *external* group via docket.groupName()
|2.0              | /v2/api-docs                | implicit *default* group
|2.0              | /v2/api-docs?group=external | *external* group via docket.groupName()
|=======================

To customize these endpoints, loading a http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/context/annotation/PropertySource.html[property source] with the following properties
allows the properties to be  overridden

[options="header,footer"]
|=======================
|Swagger version | Override property
|1.2             | springfox.documentation.swagger.v1.path
|2.0             | springfox.documentation.swagger.v2.path
|=======================

=== Overriding property datatypes

Using the ```ApiModelProperty#dataType``` we can override the inferred data types. However it is restricted
 to only allow data types to be specified with a fully qualified class name. For e.g. if we have the following
 definition

```java

// if com.qualified.ReplaceWith is not a Class that can be created using Class.forName(...)
// Original will be replaced with the new class
@ApiModelProperty(dataType = "com.qualified.ReplacedWith")
public Original getOriginal() { ... }

// if ReplaceWith is not a Class that can be created using Class.forName(...) Original will be preserved
@ApiModelProperty(dataType = "ReplaceWith")
public Original getAnotherOriginal() { ... }
```

=== Docket XML Configuration

To use the plugin you must create a spring java configuration class which uses spring's `@Configuration`.
This config class must then be defined in your xml application context.


```xml
<!-- Required so springfox can access spring's RequestMappingHandlerMapping  -->
<mvc:annotation-driven/>

<!-- Required to enable Spring post processing on @Configuration classes. -->
<context:annotation-config/>

<bean class="com.yourapp.configuration.MySwaggerConfig"/>
```

```java

@Configuration
@EnableSwagger //Loads the spring beans required by the framework
public class MySwaggerConfig {

   /**
    * Every Docket bean is picked up by the swagger-mvc framework - allowing for multiple
    * swagger groups i.e. same code base multiple swagger resource listings.
    */
   @Bean
   public Docket customDocket(){
      return new Docket(); //some customization goes here
   }

}
```


=== Docket Spring Java Configuration

- Use the `@EnableSwagger` or `@EnableSwagger2` annotation.
- Define one or more Docket instances using springs `@Bean` annotation.

```java
@Configuration
@EnableWebMvc //NOTE: Only needed in a non-springboot application
@EnableSwagger2
@ComponentScan("com.myapp.controllers")
public class CustomJavaPluginConfig {


   @Bean //Don't forget the @Bean annotation
   public Docket customImplementation(){
      return new Docket()
            .apiInfo(apiInfo());
            //... more options available

   }
{'fraction_non_alphanumeric': 0.10091109884041966, 'fraction_numerical': 0.006212037548315848, 'mean_word_length': 3.9807493984187006, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 17, 'https://': 8, 'lorem ipsum': 0, 'www.': 2, 'xml': 4}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4720701', 'n_tokens_mistral': 3792, 'n_tokens_neox': 3592, 'n_words': 1414}