Added documentation on externalizing descriptions to properties

resolves #1232

== 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
 application 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
|1.2              | /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
|=======================

=== Configuring startup.
If you'd like to delay the startup of springfox, you could choose to set auto-startup to false. The property to use
is `springfox.documentation.auto-startup` and this could either be passed in as a `-D` jvm arg or via a property in
`application.yml/properties` file.
[options="header,footer"]
|=======================
|Override property | description
| true | This is the default value, which starts scanning for endpoints automatically when
the spring contexts is refreshed.
| false | This setting starts scanning for endpoints only when when the `Lifecycle#start()` method is called explicitly.
This is very useful for frameworks like grails that has its own lifecycle. It indicates that the library
user is responsible for starting the `DocumentationPluginsBootStrapper` lifecycle.
|=======================

WARNING: Change this default to `false` with caution. This implies managing the startup of the plugins prior to
requesting the swagger endpoints in a thread-safe manner.

=== Overriding descriptions via properties
Added support for resolving properties in property sources to replace expressions in certain annotations. In order to
 use it simply define properties in `application.properties`, `application.yml` file or property files in your
 classpath with values that you'd like to see replaced in known annotations. For e.g. `@ApiModelProperty(value="${property1.description}")`
 will evaluate `property1.description` from the available properties. If none is found, it will render the
 un-resolved expression as-is.

Currently supported list of annotations are in order of priority within the annotation:

[options="header,footer"]
|=======================
|Annotation | attribute | target property| description
| ApiModelProperty | value | ModelProperty#description |e.g. `@ApiModelProperty(value="${property1.description}")`
| ApiModelProperty | description | ModelProperty#description |e.g. `@ApiModelProperty(notes="${property1.description}")`
| ApiParam | value | Parameter#description |e.g. `@ApiParam(value="${param1.description}")`
| ApiImplicitParam | value | Parameter#description |e.g. `@ApiImplicitParam(value="${param1.description}")`
| ApiOperation | notes | Operation#notes |e.g. `@ApiOperation(notes="${operation1.description}")`
| ApiOperation | summary | Operation#summary |e.g. `@ApiOperation(value="${operation1.summary}")`
| RequestParam | defaultValue | Parameter#defaultValue |e.g. `@RequestParam(defaultValue="${param1.defaultValue}")`
| RequestHeader | defaultValue | Parameter#defaultValue |e.g. `@RequestHeader(defaultValue="${param1.defaultValue}")`
|=======================

=== 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

[source,java,linenums]
----

// 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() { ... }

----

NOTE: In the case of `ApiImplicitParam#dataType`, since the type itself is usually a scalar type (string, int)
use one of the base types specified in the Types class =>
`springfox-schema/src/main/java/springfox/documentation/schema/Types.java`

[source,groovy,linenums]
----
include::../../springfox-schema/src/main/java/springfox/documentation/schema/Types.java[lines=42..55]
----

=== 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

   }

   //...
}
```

=== Support for documentation from property file lookup

Starting with `2.7.0` we support looking up description from the following annotations given a property just like
property place holders resolve a value annotation `@Value(${key})`. The following annotations attributes support
description resolution.

- `@ApiParam#value()`
- `@ApiImplicitParam#value()`
- `@ApiModelProperty#value()`
- `@ApiOperation#value()`
- `@ApiOperation#notes()`
- `@RequestParam#defaultValue()`
- `@RequestHeader#defaultValue()`

Below are examples of how it would work

[[controller-description]]Controller Example
[source,java]
.SomeController.java
----

  @ApiOperation(value = "Find pet by Status",
      notes = "${SomeController.findPetsByStatus.notes}"...) //<1>
  @RequestMapping(value = "/findByStatus", method = RequestMethod.GET, params = {"status"})
  public Pet findPetsByStatus(
      @ApiParam(value = "${SomeController.findPetsByStatus.status}", //<2>
           required = true,...)
      @RequestParam("status",
          defaultValue="${SomeController.findPetsByStatus.status.default}") String status) { //<3>
      //...
  }

  @ApiOperation(notes = "Operation 2", value = "${SomeController.operation2.value}"...) //<4>
  @ApiImplicitParams(
      @ApiImplicitParam(name="header1", value="${SomeController.operation2.header1}", ...) //<5>
  )
  @RequestMapping(value = "operation2", method = RequestMethod.POST)
  public ResponseEntity<String> operation2() {
    return ResponseEntity.ok("");
  }
----

<1> Example of `@ApiOperation#notes()`
<2> Example of `@ApiParam#value()
<3> Example of `@RequestParam#defaultValue()`
<4> Example of `@ApiOperation#value()`
<5> Example of `@ApiImplicitParams#value()`

[[model-description]]Model Example

[source,java]
.SomeModel.java
----
  public class SomeModel {
    @ApiModelProperty(value = "${SomeModel.someProperty}", ...) //<1>
    private long someProperty;
  }
----

<1> Example of `@ApiModelProperty#value()`

To provide these properties via external properties just add it to your application property file or any property
source configured by the application as shown below. When a property place holder cannot be found the default
behavior is to echo the expression as-is.

[source,properties]
.application.properties
----
SomeController.findPetsByStatus.notes=Finds pets by status
SomeController.findPetsByStatus.status=Status could be one of ...
SomeController.operation2.header1=Header for bla bla...
SomeController.operation2.value=Operation 2 do something...
SomeModel.someProperty=Some property description
----

==== Swagger group

A swagger group is a concept introduced by this library which is simply a unique identifier for a Swagger Resource Listing
within your application. The reason this concept was introduced was to support applications which require more than one
Resource Listing. Why would you need more than one Resource Listing?
- A single Spring Web MVC  application serves more than one API e.g. publicly facing and internally facing.
- A single Spring Web MVC  application serves multiple versions of the same API. e.g. v1 and v2

In most cases an application will not need more than one Resource Listing and the concept of swagger groups can be ignored.

==== Configuring the output of _operationId_ in a Swagger 2.0 spec

As defined https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#fixed-fields-5[`operationId` was
introduced] in the Swagger 2.0 spec, the `operationId` parameter, which was referred to as `nickname` in pre-2.0
versions of the Swagger spec, provides the author a means by which to describe an API operation with a friendly name
. This field is often used by consumers of a Swagger 2.0 spec in order to name functions in generated clients. An
example of this can be seen in the https://github.com/swagger-api/swagger-codegen[swagger-codegen project].

===== The default value of `operationId` according to Springfox

By default, when using Springfox in Swagger 2.0 mode, the value of `operationID` will be rendered using the
following structure: "`[java_method_name_here]Using[HTTP_verb_here]`". For example, if one has a method `getPets()`
connected to an HTTP GET verb, Springfox will render `getPetsUsingGET` for the operationId.

====== Given this annotated method ...

```java
@ApiOperation(value = "")
@RequestMapping(value = "/pets", method = RequestMethod.GET)
public Model getAllThePets() {
    ...
}
```

====== the default `operationId` will render looking like this:

```json

"paths": {
  "/pets": {
    "get": {
            ...
      "operationId":"getAllThePetsUsingGET"
      ...
    }
  }
}

```

===== Customizing the value of _operationId_

In the event you wish to override the default `operationId` which Springfox renders, you may do so by providing the
`nickname` element in an `@ApiOperation` annotation.

====== Given this annotated method ...

```java
@ApiOperation(value = "", nickname = "getMeAllThePetsPlease")
@RequestMapping(value = "/pets", method = RequestMethod.GET)
public Model getAllThePets() {
    ...
}
```

====== ... the customized *operationId* will render looking like this:

```json

"paths": {
  "/pets": {
    "get": {
            ...
      "operationId":"getMeAllThePetsPlease"
      ...
    }
  }
}

```

==== Changing how Generic Types are Named

By default, types with generics will be labeled with '\u00ab'(<<), '\u00bb'(>>), and commas. This can be problematic
with things like swagger-codegen. You can override this behavior by implementing your own `GenericTypeNamingStrategy`.
For example, if you wanted `List<String>` to be encoded as 'ListOfString' and `Map<String, Object>`
to be encoded as 'MapOfStringAndObject' you could set the `forCodeGeneration` customization option to `true` during
plugin customization:

```java
 docket.forCodeGeneration(true|false);
```

=== Caching

The caching feature that was introduced in 2.1.0 has been removed. Springfox no longer uses the cache abstraction to
improve performance the api scanners and readers. It has been rolled into the library as an internal implementation
detail as of 2.1.2. This is a runtime breaking change, however, since its not really breaking api compatibility change
other than the introduction of configuration change in consuming applications, we're not incrementing the minor version.

=== Configuring Security Schemes and Contexts an Overview

The security provisions in SpringFox at a high level, without getting into the code, has different pieces
that all work together in concert

- The API itself needs to be protected. This is achieved by using, for simplicity sake, spring security and may also
use a combination of servlet container and tomcat/jersey etc.
- The security scheme which describes the techniques you've used to protect the api. Spring fox supports whatever
schemes swagger specification supports (ApiKey, BasicAuth and OAuth2 (certain profiles))
- Finally the security contexts which actually provides information on which api's are protected by which schemes. I
think in your example, you're missing the last piece of the puzzle, the security context see  xref:getting-started-spring-boot[15].

=== Example application

For an examples for spring-boot, vanilla spring applications take a look https://github.com/springfox/springfox-demos[examples]
in the demo application.

== Configuring springfox-staticdocs

IMPORTANT: Support for this module has been deprecated in 2.7.0. Since swagger2markup doesnt support jdk6 anymore it is
difficult for build to co-exist with the newer version of swagger2markup. Please use the
_latest_ instructions provided in the awesome https://github.com/Swagger2Markup/swagger2markup[Swagger2Markup Library].

== Security

Thanks to https://github.com/mojaiq[Javed Mohammed] we now have an example https://github.com/springfox/springfox-oath2-demo[oauth demo].

NOTE: this is based on swagger-ui pre 3.x

== 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
 application 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
|1.2              | /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
|=======================

=== Configuring startup.
If you'd like to delay the startup of springfox, you could choose to set auto-startup to false. The property to use
is `springfox.documentation.auto-startup` and this could either be passed in as a `-D` jvm arg or via a property in
`application.yml/properties` file.
[options="header,footer"]
|=======================
|Override property | description
| true | This is the default value, which starts scanning for endpoints automatically when
the spring contexts is refreshed.
| false | This setting starts scanning for endpoints only when when the `Lifecycle#start()` method is called explicitly.
This is very useful for frameworks like grails that has its own lifecycle. It indicates that the library
user is responsible for starting the `DocumentationPluginsBootStrapper` lifecycle.
|=======================

WARNING: Change this default to `false` with caution. This implies managing the startup of the plugins prior to
requesting the swagger endpoints in a thread-safe manner.

=== 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

[source,java,linenums]
----

// 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() { ... }

----

NOTE: In the case of `ApiImplicitParam#dataType`, since the type itself is usually a scalar type (string, int)
use one of the base types specified in the Types class =>
`springfox-schema/src/main/java/springfox/documentation/schema/Types.java`

[source,groovy,linenums]
----
include::../../springfox-schema/src/main/java/springfox/documentation/schema/Types.java[lines=42..55]
----

=== 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

   }

   //...
}
```

=== Support for documentation from property file lookup

Starting with `2.7.0` we support looking up description from the following annotations given a property just like
property place holders resolve a value annotation `@Value(${key})`. The following annotations attributes support
description resolution.

- `@ApiParam#value()`
- `@ApiImplicitParam#value()`
- `@ApiModelProperty#value()`
- `@ApiOperation#value()`
- `@ApiOperation#notes()`
- `@RequestParam#defaultValue()`
- `@RequestHeader#defaultValue()`

Below are examples of how it would work

[[controller-description]]Controller Example
[source,java]
.SomeController.java
----

  @ApiOperation(value = "Find pet by Status",
      notes = "${SomeController.findPetsByStatus.notes}"...) //<1>
  @RequestMapping(value = "/findByStatus", method = RequestMethod.GET, params = {"status"})
  public Pet findPetsByStatus(
      @ApiParam(value = "${SomeController.findPetsByStatus.status}", //<2>
           required = true,...)
      @RequestParam("status",
          defaultValue="${SomeController.findPetsByStatus.status.default}") String status) { //<3>
      //...
  }

  @ApiOperation(notes = "Operation 2", value = "${SomeController.operation2.value}"...) //<4>
  @ApiImplicitParams(
      @ApiImplicitParam(name="header1", value="${SomeController.operation2.header1}", ...) //<5>
  )
  @RequestMapping(value = "operation2", method = RequestMethod.POST)
  public ResponseEntity<String> operation2() {
    return ResponseEntity.ok("");
  }
----

<1> Example of `@ApiOperation#notes()`
<2> Example of `@ApiParam#value()
<3> Example of `@RequestParam#defaultValue()`
<4> Example of `@ApiOperation#value()`
<5> Example of `@ApiImplicitParams#value()`

[[model-description]]Model Example

[source,java]
.SomeModel.java
----
  public class SomeModel {
    @ApiModelProperty(value = "${SomeModel.someProperty}", ...) //<1>
    private long someProperty;
  }
----

<1> Example of `@ApiModelProperty#value()`

To provide these properties via external properties just add it to your application property file or any property
source configured by the application as shown below. When a property place holder cannot be found the default
behavior is to echo the expression as-is.

[source,properties]
.application.properties
----
SomeController.findPetsByStatus.notes=Finds pets by status
SomeController.findPetsByStatus.status=Status could be one of ...
SomeController.operation2.header1=Header for bla bla...
SomeController.operation2.value=Operation 2 do something...
SomeModel.someProperty=Some property description
----

==== Swagger group

A swagger group is a concept introduced by this library which is simply a unique identifier for a Swagger Resource Listing
within your application. The reason this concept was introduced was to support applications which require more than one
Resource Listing. Why would you need more than one Resource Listing?
- A single Spring Web MVC  application serves more than one API e.g. publicly facing and internally facing.
- A single Spring Web MVC  application serves multiple versions of the same API. e.g. v1 and v2

In most cases an application will not need more than one Resource Listing and the concept of swagger groups can be ignored.

==== Configuring the output of _operationId_ in a Swagger 2.0 spec

As defined https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#fixed-fields-5[`operationId` was
introduced] in the Swagger 2.0 spec, the `operationId` parameter, which was referred to as `nickname` in pre-2.0
versions of the Swagger spec, provides the author a means by which to describe an API operation with a friendly name
. This field is often used by consumers of a Swagger 2.0 spec in order to name functions in generated clients. An
example of this can be seen in the https://github.com/swagger-api/swagger-codegen[swagger-codegen project].

===== The default value of `operationId` according to Springfox

By default, when using Springfox in Swagger 2.0 mode, the value of `operationID` will be rendered using the
following structure: "`[java_method_name_here]Using[HTTP_verb_here]`". For example, if one has a method `getPets()`
connected to an HTTP GET verb, Springfox will render `getPetsUsingGET` for the operationId.

====== Given this annotated method ...

```java
@ApiOperation(value = "")
@RequestMapping(value = "/pets", method = RequestMethod.GET)
public Model getAllThePets() {
    ...
}
```

====== the default `operationId` will render looking like this:

```json

"paths": {
  "/pets": {
    "get": {
            ...
      "operationId":"getAllThePetsUsingGET"
      ...
    }
  }
}

```

===== Customizing the value of _operationId_

In the event you wish to override the default `operationId` which Springfox renders, you may do so by providing the
`nickname` element in an `@ApiOperation` annotation.

====== Given this annotated method ...

```java
@ApiOperation(value = "", nickname = "getMeAllThePetsPlease")
@RequestMapping(value = "/pets", method = RequestMethod.GET)
public Model getAllThePets() {
    ...
}
```

====== ... the customized *operationId* will render looking like this:

```json

"paths": {
  "/pets": {
    "get": {
            ...
      "operationId":"getMeAllThePetsPlease"
      ...
    }
  }
}

```

==== Changing how Generic Types are Named

By default, types with generics will be labeled with '\u00ab'(<<), '\u00bb'(>>), and commas. This can be problematic
with things like swagger-codegen. You can override this behavior by implementing your own `GenericTypeNamingStrategy`.
For example, if you wanted `List<String>` to be encoded as 'ListOfString' and `Map<String, Object>`
to be encoded as 'MapOfStringAndObject' you could set the `forCodeGeneration` customization option to `true` during
plugin customization:

```java
 docket.forCodeGeneration(true|false);
```

=== Caching

The caching feature that was introduced in 2.1.0 has been removed. Springfox no longer uses the cache abstraction to
improve performance the api scanners and readers. It has been rolled into the library as an internal implementation
detail as of 2.1.2. This is a runtime breaking change, however, since its not really breaking api compatibility change
other than the introduction of configuration change in consuming applications, we're not incrementing the minor version.

=== Configuring Security Schemes and Contexts an Overview

The security provisions in SpringFox at a high level, without getting into the code, has different pieces
that all work together in concert

- The API itself needs to be protected. This is achieved by using, for simplicity sake, spring security and may also
use a combination of servlet container and tomcat/jersey etc.
- The security scheme which describes the techniques you've used to protect the api. Spring fox supports whatever
schemes swagger specification supports (ApiKey, BasicAuth and OAuth2 (certain profiles))
- Finally the security contexts which actually provides information on which api's are protected by which schemes. I
think in your example, you're missing the last piece of the puzzle, the security context see  xref:getting-started-spring-boot[15].

=== Example application

For an examples for spring-boot, vanilla spring applications take a look https://github.com/springfox/springfox-demos[examples]
in the demo application.

== Configuring springfox-staticdocs

IMPORTANT: Support for this module has been deprecated in 2.7.0. Since swagger2markup doesnt support jdk6 anymore it is
difficult for build to co-exist with the newer version of swagger2markup. Please use the
_latest_ instructions provided in the awesome https://github.com/Swagger2Markup/swagger2markup[Swagger2Markup Library].

== Security

Thanks to https://github.com/mojaiq[Javed Mohammed] we now have an example https://github.com/springfox/springfox-oath2-demo[oauth demo].

NOTE: this is based on swagger-ui pre 3.x


BXMSDOC-1910 updated Aliases formatting

BXMSDOC-1910 updated Aliases formatting

[[bxms_rn_whats_new]]
= What's New

This section highlights new features in {PRODUCT} {PRODUCT_VERSION} Limited Availability.

== Business Central

=== Improved Navigation

.Navigation between views
You can now navigate as follows:

* From a process instance to the associated jobs
* From a job to the associated process instance
* From a process instance to the associated tasks

.Business Central Home page
The Business Central Home page has been redesigned for easier navigation. For more information, see the "Business Central" chapter of the _{PRODUCT} User Guide_.

=== Guided Decision Table
* Guided Decision Table has a new wizard for creating and editing columns.
* Hit policies are now available. Hit policies determine the order in which rules (rows) in a guided decision table are applied.
* New support to display multiple linked guided decision tables in the Guided Decision Table Editor has been added.

=== Projects Metrics dashboard
A new dashboard is now available for every project listed in the Projects perspective. The Projects Metrics dashboard shows all of your project contribution metrics in one place. This new dashboard replaces the Contributors page, which was part of the Authoring group. For more information, see the "Projects Metrics dashboard" section of the _{PRODUCT} User Guide_.

=== Team Metrics dashboard
The Team Metrics dashboard shows all project metrics by team in a single page. This new dashboard replaces the older Contributors page, which was part of the Authoring group. For more information, see the "Team Metrics dashboard" section of the _{PRODUCT} User Guide_.

=== New columns available on process instances, tasks, and jobs
The following columns have been added to the corresponding perspectives:

* Process instance list perspective: Last update and correlation key.
* Task list: Last update, correlation key (of the associated process instance ID), process instance description (of the associated process instance).
* Jobs perspective: Name of the associated process (if any), ID of the associated process instance (if any), Description of the associated process instance (if any).

=== Advanced search filter
You can now search for specific data by using the *Search* tab on the Jobs, Process Instances, Tasks Administration, and Execution Errors perspectives. For information about the new search feature, see the "Using the advanced search filter pages" section of the _{PRODUCT} {RELEASE} User Guide_.

=== New Task List and Task Administration perspectives
The former Task List perspective has been divided into the Tasks List and Task Administration perspectives. The Task List perspective is used by task operators to work with their assigned (or potentially assigned) tasks. The Task Administration perspective is used by administrators to manage tasks assigned to other users. This perspective is only available for users with admin or process-admin roles. It is similar to the Admin filter tab on the former Task List perspective.

=== Improved validation in deployment descriptor editor

The deployment descriptor editor in Business Central has been improved to validate data entered for the following:

* Work item handlers
* Event listeners
* Marshalling strategies
* Globals
* Environment entries
* Configuration

Validation is performed automatically when a build is invoked or manually when a user clicks *Validate*.

=== Error Handling
The system now detects and stores execution errors such as exceptions while running a process instance or a job after the maximum number of retries has been exceeded. If an error occurs, an event is generated that contains the following data:

--
[cols="1,2",options="header"]
|===
| Data
| Fields

.3+| Process model
| processModelID
| processModelVersion
| processModelName

.2+| Process instance that has failed
| processInstanceID
| customProcessID

.5+| Activity that has failed
| activityID
| activityName
| activityType
| iteration
| status

.2+| Error data
| errorMessage: Message with the error that has occurred.
| errorStack: Stack with error detail.
|===
--

The process instance list includes a new column that displays the number of errors per process instance which are not marked as acknowledged. When you select the column, a window appears which will enables you to navigate to the new Error perspective.

The Execution Errors perspective lists any errors that occur during process instances or executor service jobs on a Decision Server. Use this perspective to help troubleshoot issues. It is visible to users with the admin and process-admin roles.

== Process Engine

=== Process and task administration API
A process administration API and task administration API have been introduced to simplify some of the more complex administrator use cases.
The process admin API enables you to:

* Retrieve all process definition nodes
* Cancel node instances
* Retrigger node instances
* Update the timer (absolute or relative)
* List timer instances
* Trigger nodes

The task administration API enables you to:

* Add and remove potential owners and excluded owners and business administrators
* Add and remove task inputs and outputs
* List, create, and cancel escalations and notifications

=== Advanced task routing
When tasks are assigned to a group of users, you can use pluggable task assignment strategies to automatically assign tasks to a suitable individual immediately. This enables more efficient task allocation, based on all properties associated with the task (for example potential owners and task priority but also task data that includes information such as geography, required skills, and so forth). You can use business rules to define the assignment logic, making it easy to customize this to your needs.

=== Process execution server
The process execution server (also known as kie-server) has been extended to support core engine features and offers a remote API for these operations. In addition the following architectural changes were introduced.

==== Separate Business Central from execution server
Business Central now delegates all of its requests to the execution server as well. The main advantage is that Business Central can now be used to monitor any set of execution servers. By linking the execution server to Business Central, the process and task monitoring UIs in Business Central can now connect to this execution server and show all relevant information. When multiple independent execution servers are used, you can either connect to a specific one or use the smart router to aggregate information across multiple servers.

==== Smart router
The smart router (also known as kie-server-router) can be used as a proxy to help manage multiple independent process execution servers.

==== Aliases
You can now use aliases instead of container IDs in the remote REST APIs of the execution server. For more information, see the "Editing container aliases through Business Central" section of the _{PRODUCT} User Guide_.

=== Business Central Monitoring web application
A new distribution `war` file that enables you to build custom cloud images has been added in this release.The Business Central Monitoring web application should be used with Decision Server instances to manage all run time capabilities in the cloud. This includes managing containers, process instances, tasks, and dashboards. Unlike the standard Business Central distribution, no authoring capabilities are offered.

NOTE:
For on premise deployments, use the standard Business Central `war` file.

=== Work Item archetype

To help users build custom service tasks (work items), {PRODUCT} comes with the Work Item archetype that generates the majority of items required to build a custom service task.  It does include:

* A Work Item Definition (WID) file
* The Work Item Handler implementation class
* The Work Item Handler test class

The Maven assembly (zip) packages everything at build time so it can be consumed by the Service Repository and therefore be used from within the Web Designer.

=== KIE Server Maven plugins
KIE Server has been enhanced with additional Maven plugins that enable interaction with the KIE Server and KIE Controller REST API directly from within a build. This facilitates easier integration with CI/CD pipelines when building KJars so they can be directly deployed to the execution environment (both managed and unmanaged KIE Servers).

== Business Resource Planner
* Multi-threaded partitioned search is available. Business Resource Planner now has out-of-the box support for solving a single data set by partitioning across multiple threads. This enhancement makes use of multiple CPU cores for a single problem. Partitioned search can implement geo-fencing for Vehicle Routing use cases.
* The Solution interface is deprecated. Your solution class requires only the `@PlanningSolution` annotation.
* You no longer need to define the score type in the solver configuration. Business Resource Planner now picks it up automatically from the domain model.
* The Business Resource Planner Solver editor screen now supports adding all termination types, including composite termination. The phase configuration section enables you to tweak Construction Heuristic settings and select Local Search algorithm to optimize your planning problem.
* Examples are now part of Business Central and they work offline as well. Leverage tag-based filtering to quickly access projects from the field you are interested in.
* The Business Resource Planner domain editor can now specify a planning entity difficulty. Navigate through the object hierarchy and define the sorting attributes. Several construction heuristic algorithms use this information to construct a better initial solution.
* The Business Resource Planner execution server now supports real-time planning.

[[bxms_rn_whats_new]]
= What's New

This section highlights new features in {PRODUCT} {PRODUCT_VERSION} Limited Availability.

== Business Central

=== Improved Navigation

.Navigation between views
You can now navigate as follows:

* From a process instance to the associated jobs
* From a job to the associated process instance
* From a process instance to the associated tasks

.Business Central Home page
The Business Central Home page has been redesigned for easier navigation. For more information, see the "Business Central" chapter of the _{PRODUCT} User Guide_.

=== Guided Decision Table
* Guided Decision Table has a new wizard for creating and editing columns.
* Hit policies are now available. Hit policies determine the order in which rules (rows) in a guided decision table are applied.
* New support to display multiple linked guided decision tables in the Guided Decision Table Editor has been added.

=== Projects Metrics dashboard
A new dashboard is now available for every project listed in the Projects perspective. The Projects Metrics dashboard shows all of your project contribution metrics in one place. This new dashboard replaces the Contributors page, which was part of the Authoring group. For more information, see the "Projects Metrics dashboard" section of the _{PRODUCT} User Guide_.

=== Team Metrics dashboard
The Team Metrics dashboard shows all project metrics by team in a single page. This new dashboard replaces the older Contributors page, which was part of the Authoring group. For more information, see the "Team Metrics dashboard" section of the _{PRODUCT} User Guide_.

=== New columns available on process instances, tasks, and jobs
The following columns have been added to the corresponding perspectives:

* Process instance list perspective: Last update and correlation key.
* Task list: Last update, correlation key (of the associated process instance ID), process instance description (of the associated process instance).
* Jobs perspective: Name of the associated process (if any), ID of the associated process instance (if any), Description of the associated process instance (if any).

=== Advanced search filter
You can now search for specific data by using the *Search* tab on the Jobs, Process Instances, Tasks Administration, and Execution Errors perspectives. For information about the new search feature, see the "Using the advanced search filter pages" section of the _{PRODUCT} {RELEASE} User Guide_.

=== New Task List and Task Administration perspectives
The former Task List perspective has been divided into the Tasks List and Task Administration perspectives. The Task List perspective is used by task operators to work with their assigned (or potentially assigned) tasks. The Task Administration perspective is used by administrators to manage tasks assigned to other users. This perspective is only available for users with admin or process-admin roles. It is similar to the Admin filter tab on the former Task List perspective.

=== Improved validation in deployment descriptor editor

The deployment descriptor editor in Business Central has been improved to validate data entered for the following:

* Work item handlers
* Event listeners
* Marshalling strategies
* Globals
* Environment entries
* Configuration

Validation is performed automatically when a build is invoked or manually when a user clicks *Validate*.

=== Error Handling
The system now detects and stores execution errors such as exceptions while running a process instance or a job after the maximum number of retries has been exceeded. If an error occurs, an event is generated that contains the following data:

--
[cols="1,2",options="header"]
|===
| Data
| Fields

.3+| Process model
| processModelID
| processModelVersion
| processModelName

.2+| Process instance that has failed
| processInstanceID
| customProcessID

.5+| Activity that has failed
| activityID
| activityName
| activityType
| iteration
| status

.2+| Error data
| errorMessage: Message with the error that has occurred.
| errorStack: Stack with error detail.
|===
--

The process instance list includes a new column that displays the number of errors per process instance which are not marked as acknowledged. When you select the column, a window appears which will enables you to navigate to the new Error perspective.

The Execution Errors perspective lists any errors that occur during process instances or executor service jobs on a Decision Server. Use this perspective to help troubleshoot issues. It is visible to users with the admin and process-admin roles.

== Process Engine

=== Process and task administration API
A process administration API and task administration API have been introduced to simplify some of the more complex administrator use cases.
The process admin API enables you to:

* Retrieve all process definition nodes
* Cancel node instances
* Retrigger node instances
* Update the timer (absolute or relative)
* List timer instances
* Trigger nodes

The task administration API enables you to:

* Add and remove potential owners and excluded owners and business administrators
* Add and remove task inputs and outputs
* List, create, and cancel escalations and notifications

=== Advanced task routing
When tasks are assigned to a group of users, you can use pluggable task assignment strategies to automatically assign tasks to a suitable individual immediately. This enables more efficient task allocation, based on all properties associated with the task (for example potential owners and task priority but also task data that includes information such as geography, required skills, and so forth). You can use business rules to define the assignment logic, making it easy to customize this to your needs.

=== Process execution server
The process execution server (also known as kie-server) has been extended to support core engine features and offers a remote API for these operations. In addition the following architectural changes were introduced.

==== Separate Business Central from execution server
Business Central now delegates all of its requests to the execution server as well. The main advantage is that Business Central can now be used to monitor any set of execution servers. By linking the execution server to Business Central, the process and task monitoring UIs in Business Central can now connect to this execution server and show all relevant information. When multiple independent execution servers are used, you can either connect to a specific one or use the smart router to aggregate information across multiple servers.

==== Smart router
The smart router (also known as kie-server-router) can be used as a proxy to help manage multiple independent process execution servers.

=== Aliases
You can now use aliases instead of container IDs in the remote REST APIs of the execution server. For more information, see the "Editing container aliases through Business Central" section of the _{PRODUCT} User Guide_.

=== Business Central Monitoring web application
A new distribution `war` file that enables you to build custom cloud images has been added in this release.The Business Central Monitoring web application should be used with Decision Server instances to manage all run time capabilities in the cloud. This includes managing containers, process instances, tasks, and dashboards. Unlike the standard Business Central distribution, no authoring capabilities are offered.

NOTE:
For on premise deployments, use the standard Business Central `war` file.

=== Work Item archetype

To help users build custom service tasks (work items), {PRODUCT} comes with the Work Item archetype that generates the majority of items required to build a custom service task.  It does include:

* A Work Item Definition (WID) file
* The Work Item Handler implementation class
* The Work Item Handler test class

The Maven assembly (zip) packages everything at build time so it can be consumed by the Service Repository and therefore be used from within the Web Designer.

=== KIE Server Maven plugins
KIE Server has been enhanced with additional Maven plugins that enable interaction with the KIE Server and KIE Controller REST API directly from within a build. This facilitates easier integration with CI/CD pipelines when building KJars so they can be directly deployed to the execution environment (both managed and unmanaged KIE Servers).

== Business Resource Planner
* Multi-threaded partitioned search is available. Business Resource Planner now has out-of-the box support for solving a single data set by partitioning across multiple threads. This enhancement makes use of multiple CPU cores for a single problem. Partitioned search can implement geo-fencing for Vehicle Routing use cases.
* The Solution interface is deprecated. Your solution class requires only the `@PlanningSolution` annotation.
* You no longer need to define the score type in the solver configuration. Business Resource Planner now picks it up automatically from the domain model.
* The Business Resource Planner Solver editor screen now supports adding all termination types, including composite termination. The phase configuration section enables you to tweak Construction Heuristic settings and select Local Search algorithm to optimize your planning problem.
* Examples are now part of Business Central and they work offline as well. Leverage tag-based filtering to quickly access projects from the field you are interested in.
* The Business Resource Planner domain editor can now specify a planning entity difficulty. Navigate through the object hierarchy and define the sorting attributes. Several construction heuristic algorithms use this information to construct a better initial solution.
* The Business Resource Planner execution server now supports real-time planning.