Updated the documentation

Polished the javadocs for the configuration properties fixes #3378
springfox · Jul 14, 2020 · bc9d0ca · bc9d0ca
1 parent d92928f
commit bc9d0ca
Show file tree

Hide file tree

Showing 5 changed files with 85 additions and 39 deletions.
diff --git a/docs/asciidoc/getting_started.adoc b/docs/asciidoc/getting_started.adoc
@@ -115,22 +115,43 @@ dependencies {
 
 ==== Migrating from existing 2.x version
 ===== Spring Boot Applications
-1. Remove library inclusions of earlier
+1. Remove library inclusions of earlier releases. Specifically remove `springfox-swagger2` and `springfox-swagger-ui` inclusions.
 2. Remove the `@EnableSwagger2` annotations
-3. Added the `springfox-boot-starter`
+3. Add the `springfox-boot-starter`
 4. Springfox 3.x removes dependencies on guava and other 3rd party libraries (not zero dep yet! depends on spring plugin
 and open api libraries for annotations and models) so if you used guava predicates/functions those will need to
 transition to java 8 function interfaces
 
 ===== Regular spring mvc
-1. Remove library inclusions of earlier
-2. Add `EnableOpenApi` for open API (and `@EnableSwagger2` for swagger 2.0)
-3. Added the `springfox-oas` library
+1. Remove library inclusions of earlier releases. Specifically remove `springfox-swagger2` and `springfox-swagger-ui` inclusions.
+2. For OpenAPI add the `@EnableOpenApi` annotation (and `@EnableSwagger2` for swagger 2.0)
+3. For OpenAPI add the `springfox-oas` library dependency (for swagger 2.0 use `springfox-swagger2`)
 4. Springfox 3.x removes dependencies on guava and other 3rd party libraries (not zero dep yet! depends on spring plugin
 and open api libraries for annotations and models) so if you used guava predicates/functions those will need to
 transition to java 8 function interfaces
 
-NOTE: Would love feedback to make this experience better
+===== Changes in swagger-ui
+NOTE: For non-boot applications `springfox-swagger-ui` is no longer automatically enabled by adding the dependency. It needs to be explicitly register
+using a resource handler configurer (`WebFluxConfigurer` or `WebMvcConfigurer`). Here is how it is configured in
+`springfox-boot-starter`
+
+NOTE: swagger-ui location has moved from `http://host/context-path/swagger-ui.html`  to `http://host/context-path/swagger-ui/index.html`
+OR `http://host/context-path/swagger-ui/` for short. This makes it work much better with pulling it as a web jar and turning it off
+using configuration properties if not needed.
+
+For WebMvc https://github.com/springfox/springfox/blob/master/springfox-boot-starter/src/main/java/springfox/boot/starter/autoconfigure/SwaggerUiWebMvcConfigurer.java[SwagggerUIWebMvcConfigurer.java]
+[[jackson-convention-example-1]]
+[source,java,linenums]
+----
+include::../../springfox-boot-starter/src/main/java/springfox/boot/starter/autoconfigure/SwaggerUiWebMvcConfigurer.java[tags=swagger-ui-configurer,indent=0]
+----
+
+For WebFlux https://github.com/springfox/springfox/blob/master/springfox-boot-starter/src/main/java/springfox/boot/starter/autoconfigure/SwaggerUiWebFluxConfigurer.java[SwagggerUIWebMvcConfigurer.java]
+[[jackson-convention-example-1]]
+[source,java,linenums]
+----
+include::../../springfox-boot-starter/src/main/java/springfox/boot/starter/autoconfigure/SwaggerUiWebFluxConfigurer.java[tags=swagger-ui-configurer,indent=0]
+----
 
 == Quick start guides
 === Springfox Spring MVC and Spring Boot
@@ -211,7 +232,7 @@ In version greater than 2.6.0, support for spring data rest was added.
 
 NOTE: This is still in ***incubation***.
 
-In order to use it
+In order to use it (non-spring-boot)
 
 1. add the `springfox-data-rest` dependency (via Gradle or Maven).
 2. Import the configuration from the `springfox-data-rest` module (via Java or xml config) as shown below
@@ -236,8 +257,6 @@ dependencies {
 </dependency>
 ----
 
-
-
 ==== java config
 [source,java]
 [subs="verbatim,attributes"]
@@ -255,6 +274,9 @@ Import the bean in your xml configuration by defining a bean of the following ty
 <bean class="springfox.documentation.spring.data.rest.configuration.SpringDataRestConfiguration.class" />
 ----
 
+NOTE: for spring boot, this section is not needed. Springfox will autoconfigure itself based on the detection of spring
+data rest components.
+
 === Springfox Support for JSR-303
 In version greater than 2.3.2, support for bean validation annotations was added, specifically for @NotNull, @Min,
 @Max, and @Size.
@@ -347,35 +369,10 @@ Regarding http://springfox.github.io/springfox/docs/current/#q13[where swagger-u
 and http://springfox.github.io/springfox/docs/current/#customizing-the-swagger-endpoints[where the api docs are served]
 those are totally configurable.
 
-=== Springfox RFC6570 support *incubating*
-NOTE: _Keep in mind this is experimental_!
-In order to use this feature
-
-1. Add `springfox-swagger-ui-rfc6570` instead of `springfox-swagger-ui` as a dependency
-http://mvnrepository.com/artifact/io.springfox.ui/springfox-swagger-ui-rfc6570/{springfoxRfc6570Version}[experimental swagger-ui].
+=== Springfox RFC6570 support
+NOTE: Support has been dropped experimental feature as swagger-ui and the spec itself has better support for this.
 
-For gradle:
-[source,groovy]
-[subs="verbatim,attributes"]
-----
-dependencies {
-    compile 'io.springfox.ui:springfox-swagger-ui-rfc6570:{springfoxRfc6570Version}'
-}
-----
-
-For maven:
-[source,xml]
-[subs="verbatim,attributes"]
-----
-<dependency>
-    <groupId>io.springfox.ui</groupId>
-    <artifactId>springfox-swagger-ui-rfc6570</artifactId>
-    <version>{springfoxRfc6570Version}</version>
-</dependency>
-----
-NOTE: The newer version has changed the group id from `_io.springfox_` to `_io.springfox.ui_`!
-
-- Enable url templating; (http://springfox.github.io/springfox/docs/current/#springfox-swagger2-with-spring-mvc-and-spring-boot[see #21])
+- Turn enableUrlTemplating `OFF`; (http://springfox.github.io/springfox/docs/current/#springfox-swagger2-with-spring-mvc-and-spring-boot[see #21])
 
 === Springfox Spring-Integration Support *incubating*
 NOTE: _Keep in mind this is experimental_!
@@ -459,7 +456,6 @@ cookies-based auth in the browser. (Credit: https://github.com/evser[@evser])
   }
 ----
 
-
 And configure the Docket to be secured via the `AUTHORIZATION` header:
 [source,java]
 [subs="verbatim,attributes"]

diff --git a/.../src/main/java/springfox/boot/starter/autoconfigure/SpringfoxConfigurationProperties.java b/.../src/main/java/springfox/boot/starter/autoconfigure/SpringfoxConfigurationProperties.java
@@ -5,7 +5,13 @@
 
 @ConfigurationProperties("springfox.documentation")
 public class SpringfoxConfigurationProperties {
+  /**
+   * Flag that indicates if springfox should auto start scanning services
+   */
   private boolean autoStartup = true;
+  /**
+   * Flag that indicates if springfox should scan services to produce specifications.
+   */
   private boolean enabled = true;
   @NestedConfigurationProperty
   private SwaggerConfigurationProperties swagger;
@@ -54,6 +60,11 @@ public void setSwaggerUi(SwaggerUiConfigurationProperties swaggerUi) {
     this.swaggerUi = swaggerUi;
   }
 
+  /**
+   * Configuration properties related to swagger specification.
+   *
+   * @since 3.0.0
+   */
   public static class SwaggerConfigurationProperties {
     @NestedConfigurationProperty
     private Swagger2Configuration v2;
@@ -68,9 +79,24 @@ public void setV2(Swagger2Configuration v2) {
 
   }
 
+  /**
+   * Configuration properties related to swagger 2.0 specification.
+   *
+   * @since 3.0.0
+   */
   public static class Swagger2Configuration {
+    /**
+     * Flag that disables swagger 2 related beans
+     */
     private boolean enabled = false;
+    /**
+     * Flag that toggles between generating models using v3.0.0 of the library or the 2.9.x version of the library.
+     * This flag can be changed to false, if v3.0.0 is not working as expected.
+     */
     private boolean useModelV3 = true;
+    /**
+     * Host name to use for swagger 2 specification
+     */
     private String host;
 
     public String getHost() {
@@ -97,8 +123,15 @@ public void setUseModelV3(boolean useModelV3) {
       this.useModelV3 = useModelV3;
     }
   }
-
+  /**
+   * Configuration properties related to OpenApi 3.0 specification.
+   *
+   * @since 3.0.0
+   */
   public static class OpenApiConfigurationProperties {
+    /**
+     * Flag that disables openApi related beans
+     */
     private boolean enabled = true;
 
     public boolean isEnabled() {
@@ -110,8 +143,20 @@ public void setEnabled(boolean enabled) {
     }
   }
 
+  /**
+   * Configuration properties related to swagger-ui specification.
+   *
+   * @since 3.0.0
+   */
   public static class SwaggerUiConfigurationProperties {
+    /**
+     * Flag that disables swagger-ui from being resource-handled. No swagger-ui when this is false.
+     */
     private boolean enabled = true;
+    /**
+     * Base url for swagger-ui. For e.g. setting it to /documentation will put swagger-ui
+     * at /documentation/swagger-ui/index.html
+     */
     private String baseUrl = "";
 
     public boolean isEnabled() {

diff --git a/...tarter/src/main/java/springfox/boot/starter/autoconfigure/SwaggerUiWebFluxConfigurer.java b/...tarter/src/main/java/springfox/boot/starter/autoconfigure/SwaggerUiWebFluxConfigurer.java
@@ -4,6 +4,7 @@
 import org.springframework.web.reactive.config.ResourceHandlerRegistry;
 import org.springframework.web.reactive.config.WebFluxConfigurer;
 
+// tag::swagger-ui-configurer[]
 public class SwaggerUiWebFluxConfigurer implements WebFluxConfigurer {
   private final String baseUrl;
 
@@ -20,3 +21,4 @@ public void addResourceHandlers(ResourceHandlerRegistry registry) {
         .resourceChain(false);
   }
 }
+// end::swagger-ui-configurer[]
diff --git a/...starter/src/main/java/springfox/boot/starter/autoconfigure/SwaggerUiWebMvcConfigurer.java b/...starter/src/main/java/springfox/boot/starter/autoconfigure/SwaggerUiWebMvcConfigurer.java
@@ -5,6 +5,7 @@
 import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
 import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
 
+// tag::swagger-ui-configurer[]
 public class SwaggerUiWebMvcConfigurer implements WebMvcConfigurer {
   private final String baseUrl;
 
@@ -27,3 +28,4 @@ public void addViewControllers(ViewControllerRegistry registry) {
         .setViewName("forward:" + baseUrl + "/swagger-ui/index.html");
   }
 }
+// end::swagger-ui-configurer[]
diff --git a/swagger-contract-tests/src/main/resources/application.properties b/swagger-contract-tests/src/main/resources/application.properties
@@ -1,3 +1,4 @@
 spring.jpa.hibernate.ddl-auto=none
 logging.level.springfox.documentation=DEBUG
 #server.servlet.context-path=/context
+spring.activemq.broker-url=