Skip to content

Commit

Permalink
Merge branch 'master' into feature/spring5
Browse files Browse the repository at this point in the history 
Conflicts:
	springfox-data-rest/src/main/java/springfox/documentation/spring/data/rest/EntityContext.java
	springfox-data-rest/src/main/java/springfox/documentation/spring/data/rest/EntityDeleteExtractor.java
	springfox-data-rest/src/main/java/springfox/documentation/spring/data/rest/EntityFindAllExtractor.java
	springfox-data-rest/src/main/java/springfox/documentation/spring/data/rest/EntityFindOneExtractor.java
	springfox-data-rest/src/main/java/springfox/documentation/spring/data/rest/EntitySaveExtractor.java
	springfox-data-rest/src/main/java/springfox/documentation/spring/data/rest/EntityServicesProvider.java
	swagger-contract-tests/build.gradle
  • Loading branch information
@iles-2e
iles-2e committed Apr 24, 2018
2 parents 2c7ecc6 + 0b9bd49 commit 63b2d5c
Show file tree
Hide file tree
Showing 54 changed files with 6,044 additions and 1,398 deletions.
2 changes: 1 addition & 1 deletion .version
View file
Original file line number Diff line number Diff line change
@@ -1 +1 @@
2.8.1-SNAPSHOT
2.9.0-SNAPSHOT
138 changes: 116 additions & 22 deletions docs/asciidoc/current-documentation.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,9 @@ 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
.Example configuration
[source,java,linenums]
----
import static springfox.documentation.builders.PathSelectors.*;
import static com.google.common.base.Predicates.*;
Expand Down Expand Up @@ -44,8 +46,7 @@ to this is the ability to provide an expressive predicate based for api selectio
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].
Expand Down Expand Up @@ -75,6 +76,7 @@ good example of where this breaks down is the following http://stackoverflow.com

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

.api docs default paths
[options="header,footer"]
|=======================
|Swagger version | Documentation Url | Group
Expand All @@ -87,19 +89,96 @@ By default the swagger service descriptions are generated at the following urls
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

.api docs path properties
[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.

.startup properties
[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:

.description resolution targets
[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}")`
|===

For a detailed explanation <<property-file-lookup, see here>>.
=== 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

.Example data type override
[source,java,linenums]
----
Expand All @@ -118,9 +197,10 @@ NOTE: In the case of `ApiImplicitParam#dataType`, since the type itself is usual
use one of the base types specified in the Types class =>
`springfox-schema/src/main/java/springfox/documentation/schema/Types.java`

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


Expand All @@ -130,17 +210,21 @@ To use the plugin you must create a spring java configuration class which uses s
This config class must then be defined in your xml application context.


```xml
.Xml Configuration
[source,xml,linenums]
----
<!-- 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 bean pulled into xml a configuration as a bean
[source,java,linenums]
----
@Configuration
@EnableSwagger //Loads the spring beans required by the framework
Expand All @@ -156,15 +240,17 @@ public class MySwaggerConfig {
}
}
```
----


=== Docket Spring Java Configuration

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

```java
.Java Configuration
[source,java,linenums]
----
@Configuration
@EnableWebMvc //NOTE: Only needed in a non-springboot application
@EnableSwagger2
Expand All @@ -182,8 +268,9 @@ public class CustomJavaPluginConfig {
//...
}
```
----

[[property-file-lookup]]
=== 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
Expand Down Expand Up @@ -233,7 +320,6 @@ Below are examples of how it would work
<5> Example of `@ApiImplicitParams#value()`

[[model-description]]Model Example

[source,java]
.SomeModel.java
----
Expand Down Expand Up @@ -285,17 +371,21 @@ connected to an HTTP GET verb, Springfox will render `getPetsUsingGET` for the o

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

```java
.Standard Annotation On Method
[source,java,linenums]
----
@ApiOperation(value = "")
@RequestMapping(value = "/pets", method = RequestMethod.GET)
public Model getAllThePets() {
...
}
```
----

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

```json
.Default Rendered Operation Id
[source,json,linenums]
----
"paths": {
"/pets": {
Expand All @@ -307,7 +397,7 @@ public Model getAllThePets() {
}
}
```
----

===== Customizing the value of _operationId_

Expand All @@ -316,17 +406,21 @@ In the event you wish to override the default `operationId` which Springfox rend

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

```java
.Nickname overrides default operationId
[source,java,linenums]
----
@ApiOperation(value = "", nickname = "getMeAllThePetsPlease")
@RequestMapping(value = "/pets", method = RequestMethod.GET)
public Model getAllThePets() {
...
}
```
----

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

```json
.Default Rendered Operation Id
[source,json,linenums]
----
"paths": {
"/pets": {
Expand All @@ -337,8 +431,7 @@ public Model getAllThePets() {
}
}
}

```
----

==== Changing how Generic Types are Named

Expand All @@ -348,9 +441,10 @@ For example, if you wanted `List<String>` to be encoded as 'ListOfString' and `M
to be encoded as 'MapOfStringAndObject' you could set the `forCodeGeneration` customization option to `true` during
plugin customization:

```java
[source,json,linenums]
----
docket.forCodeGeneration(true|false);
```
----

=== Caching

Expand Down
11 changes: 9 additions & 2 deletions docs/asciidoc/extensibility.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,14 @@ TIP: The ___same___ patterns apply to all of the extensibility mechanisms

That is it!

==== Example OperationBuilderPlugin

This example by https://github.com/koderman[@koderman] is a custom extension for https://aws.amazon.com/api-gateway/[AWS Amazon Api Gateway] integration.

++++
<script src="https://gist.github.com/koderman/d49a67274e33f03405a8e45672794968.js"></script>
++++

==== Example ParameterBuilderPlugin

Here is an example of how to add parameters by hand.
Expand Down Expand Up @@ -179,8 +187,7 @@ include::../../springfox-data-rest/src/main/java/springfox/documentation/spring/

=== Aggregating multiple swagger specifications in the same swagger-ui

You need to create a bean that implements the https://github
.com/springfox/springfox/blob/cef36c0b0a3e20ef2cb0c23a76ee34866abaf490/springfox-swagger-common/src/main/java/springfox/documentation/swagger/web/SwaggerResourcesProvider.java#L25-L26[`SwaggerResourcesProvider`]
You need to create a bean that implements the https://github.com/springfox/springfox/blob/cef36c0b0a3e20ef2cb0c23a76ee34866abaf490/springfox-swagger-common/src/main/java/springfox/documentation/swagger/web/SwaggerResourcesProvider.java#L25-L26[`SwaggerResourcesProvider`]
interface. Typically you'd have to make a composite bean that uses multiple https://github.com/springfox/springfox/blob/cef36c0b0a3e20ef2cb0c23a76ee34866abaf490/springfox-swagger-common/src/main/java/springfox/documentation/swagger/web/InMemorySwaggerResourcesProvider.java#L38[InMemorySwaggerResourcesProvider]
and adds your own json file to it as well.

Expand Down

0 comments on commit 63b2d5c

Please sign in to comment.