Support Spring REST Docs 3.0.0 (#211) (#225)

* Support Spring REST Docs 3.0.0 (#211)

According to spring-rest-docs 'requestParameters' are replaced by
'queryParameters' and 'formParameters'.
If 'requestParameters' are used to document the API, this must be replaced
by one of the new functions

Upgrades (needed to use spring-rest-docs 3.0.0):
* gradle 7.6
* kotlin 1.7.10
* spring-boot 3.0.2
* java 17

* Use java-17 in travis ci

* use kotlin 1.7.22 as there are runtime dependencies to this version

* Update generators and gradle plugin for rest-docs v3

.travis.yml

@@ -1,6 +1,6 @@
 dist: focal
 before_install:
-  - sudo apt-get install -y openjdk-8-jdk
+  - sudo apt-get install -y openjdk-17-jdk
 before_cache:
 - rm -f  $HOME/.gradle/caches/modules-2/modules-2.lock
 - rm -fr $HOME/.gradle/caches/*/plugin-resolution/
@@ -25,7 +25,7 @@ env:
   global:
   - CI_NAME=travis-ci
   - SIGNING_KEYRING_FILE="${TRAVIS_BUILD_DIR}/secret-keys.gpg"
-  - JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
+  - JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
   # coveralls
   - secure: "nOkY2AcR5Z7hKKzi+zCzmzPk+xiRRrJjGliDJnHnEO7g+iJ8SmT+thHuMFcXqvjxJ006LbR3GPB8M8qgFXFDPEUDRPppShi3waOm1ddlM2iXh9kbCoROoioyRO+F07deH6ExibkLbu/xq3WwAAw7lx/ZP+buc2R2VCbV0nLKP9iE4nHQX8msLgmU1LjWf0Au1Pgl2eWXV0J4/ZJOvcVu9hvBf1Ow4C7BNb0KZmMjeT9uMK0hiGpb9VVbwedOWfsbaFmqmKYqVKS8UtNmG+HBjvZfajrIARKRPc9w9uEvfl4E1H/J7PJLy2kOrCOauj8LMu6DduSrWcg08T5VnH51cavSAsWWG1ImTgEsUBNpllc9r1XLhQCLQ1TWCgGmleqYjZ2ySvg0MQpFjTgXMZC+aDkjZjcEeq3BgrncAR/bcG4ByrZBWyoEXDxBwoMZnkryTxK07UUgXRXdjJUldJ5CQW9oSfd+oEXKJyqQGNt0ob3S0sRS5uhrKniK+6Mwzxf6vXeYvn2fVP5j3hocUz4XzDJQoDDmJi6D4BpwksqJ81CNOHpyeDIOhdXxvA/J8DMCK0Q7tTSbnSOxItaht56CSxqqLSGax3/4Nr+5QX9jpmdJ03HdpP+MOuIl6dZCmE4/w1IFaFEfhpETPlnWZHl1BsOt7omDeW7yCttDq3Y1mXU="
   # gradle plugin portal

build.gradle.kts

@@ -12,7 +12,7 @@ plugins {
     id("pl.allegro.tech.build.axion-release") version "1.9.2"
     jacoco
     java
-    kotlin("jvm") version "1.4.20" apply false
+    kotlin("jvm") version "1.7.22" apply false
     `maven-publish`
 }
 
@@ -58,12 +58,12 @@ allprojects {
 subprojects {
 
     val jacksonVersion by extra { "2.12.2" }
-    val springBootVersion by extra { "2.1.9.RELEASE" }
-    val springRestDocsVersion by extra { "2.0.4.RELEASE" }
+    val springBootVersion by extra { "3.0.2" }
+    val springRestDocsVersion by extra { "3.0.0" }
     val junitVersion by extra { "5.4.2" }
 
     tasks.withType<KotlinCompile> {
-        kotlinOptions.jvmTarget = "1.8"
+        kotlinOptions.jvmTarget = "17"
     }
 
     tasks.withType<Test> {

gradle/wrapper/gradle-wrapper.properties

@@ -1,5 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-7.4.2-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.6-all.zip
+networkTimeout=10000
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

gradlew

@@ -55,7 +55,7 @@
 #       Darwin, MinGW, and NonStop.
 #
 #   (3) This script is generated from the Groovy template
-#       https://github.com/gradle/gradle/blob/master/subprojects/plugins/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+#       https://github.com/gradle/gradle/blob/HEAD/subprojects/plugins/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
 #       within the Gradle project.
 #
 #       You can find Gradle at https://github.com/gradle/gradle/.
@@ -80,10 +80,10 @@ do
     esac
 done
 
-APP_HOME=$( cd "${APP_HOME:-./}" && pwd -P ) || exit
-
-APP_NAME="Gradle"
+# This is normally unused
+# shellcheck disable=SC2034
 APP_BASE_NAME=${0##*/}
+APP_HOME=$( cd "${APP_HOME:-./}" && pwd -P ) || exit
 
 # Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
 DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
@@ -143,12 +143,16 @@ fi
 if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
     case $MAX_FD in #(
       max*)
+        # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC3045 
         MAX_FD=$( ulimit -H -n ) ||
             warn "Could not query maximum file descriptor limit"
     esac
     case $MAX_FD in  #(
       '' | soft) :;; #(
       *)
+        # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC3045 
         ulimit -n "$MAX_FD" ||
             warn "Could not set maximum file descriptor limit to $MAX_FD"
     esac
@@ -205,6 +209,12 @@ set -- \
         org.gradle.wrapper.GradleWrapperMain \
         "$@"
 
+# Stop when "xargs" is not available.
+if ! command -v xargs >/dev/null 2>&1
+then
+    die "xargs is not available"
+fi
+
 # Use "xargs" to parse quoted args.
 #
 # With -n1 it outputs one arg per line, with the quotes and backslashes removed.

gradlew.bat

@@ -14,7 +14,7 @@
 @rem limitations under the License.
 @rem
 
-@if "%DEBUG%" == "" @echo off
+@if "%DEBUG%"=="" @echo off
 @rem ##########################################################################
 @rem
 @rem  Gradle startup script for Windows
@@ -25,7 +25,8 @@
 if "%OS%"=="Windows_NT" setlocal
 
 set DIRNAME=%~dp0
-if "%DIRNAME%" == "" set DIRNAME=.
+if "%DIRNAME%"=="" set DIRNAME=.
+@rem This is normally unused
 set APP_BASE_NAME=%~n0
 set APP_HOME=%DIRNAME%
 
@@ -40,7 +41,7 @@ if defined JAVA_HOME goto findJavaFromJavaHome
 
 set JAVA_EXE=java.exe
 %JAVA_EXE% -version >NUL 2>&1
-if "%ERRORLEVEL%" == "0" goto execute
+if %ERRORLEVEL% equ 0 goto execute
 
 echo.
 echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
@@ -75,13 +76,15 @@ set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
 
 :end
 @rem End local scope for the variables with windows NT shell
-if "%ERRORLEVEL%"=="0" goto mainEnd
+if %ERRORLEVEL% equ 0 goto mainEnd
 
 :fail
 rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
 rem the _cmd.exe /c_ return code!
-if  not "" == "%GRADLE_EXIT_CONSOLE%" exit 1
-exit /b 1
+set EXIT_CODE=%ERRORLEVEL%
+if %EXIT_CODE% equ 0 set EXIT_CODE=1
+if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE%
+exit /b %EXIT_CODE%
 
 :mainEnd
 if "%OS%"=="Windows_NT" endlocal

restdocs-api-spec-gradle-plugin/src/test/kotlin/com/epages/restdocs/apispec/gradle/ApiSpecTaskTest.kt

@@ -102,7 +102,8 @@ abstract class ApiSpecTaskTest {
     "contentType" : null,
     "headers" : [ ],
     "pathParameters" : [ ],
-    "requestParameters" : [ ],
+    "queryParameters" : [ ],
+    "formParameters" : [ ],
     "requestFields" : [ ],
     "example" : null,
     "securityRequirements" : {
@@ -146,7 +147,8 @@ abstract class ApiSpecTaskTest {
       "default" : "a default value"
     } ],
     "pathParameters" : [ ],
-    "requestParameters" : [ ],
+    "queryParameters" : [ ],
+    "formParameters" : [ ],
     "requestFields" : [ ],
     "example" : null,
     "securityRequirements" : {
@@ -182,7 +184,8 @@ abstract class ApiSpecTaskTest {
     "contentType" : null,
     "headers" : [ ],
     "pathParameters" : [ ],
-    "requestParameters" : [ ],
+    "queryParameters" : [ ],
+    "formParameters" : [ ],
     "requestFields" : [ ],
     "example" : null,
     "securityRequirements" : null

restdocs-api-spec-mockmvc/build.gradle.kts

@@ -20,6 +20,7 @@ dependencies {
     testImplementation("org.springframework.boot:spring-boot-starter-test:$springBootVersion") {
         exclude("junit")
     }
+    testImplementation("org.springframework.boot:spring-boot-starter-validation:$springBootVersion")
     testImplementation("org.junit.jupiter:junit-jupiter-engine:$junitVersion")
     testImplementation("org.junit-pioneer:junit-pioneer:0.3.0")
     testImplementation("org.springframework.boot:spring-boot-starter-hateoas:$springBootVersion")

restdocs-api-spec-mockmvc/src/test/kotlin/com/epages/restdocs/apispec/ResourceSnippetIntegrationTest.kt

@@ -2,16 +2,18 @@ package com.epages.restdocs.apispec
 
 import com.epages.restdocs.apispec.ResourceDocumentation.parameterWithName
 import com.epages.restdocs.apispec.ResourceDocumentation.resource
+import jakarta.validation.constraints.NotEmpty
 import org.hibernate.validator.constraints.Length
 import org.junit.jupiter.api.extension.ExtendWith
 import org.springframework.boot.SpringApplication
 import org.springframework.boot.autoconfigure.SpringBootApplication
 import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs
 import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest
 import org.springframework.context.ConfigurableApplicationContext
+import org.springframework.hateoas.EntityModel
+import org.springframework.hateoas.IanaLinkRelations
 import org.springframework.hateoas.Link
-import org.springframework.hateoas.Resource
-import org.springframework.hateoas.mvc.BasicLinkBuilder
+import org.springframework.hateoas.server.mvc.BasicLinkBuilder.linkToCurrentMapping
 import org.springframework.http.HttpHeaders.ACCEPT
 import org.springframework.http.HttpHeaders.CONTENT_TYPE
 import org.springframework.http.ResponseEntity
@@ -26,7 +28,6 @@ import org.springframework.web.bind.annotation.RequestBody
 import org.springframework.web.bind.annotation.RequestHeader
 import org.springframework.web.bind.annotation.RestController
 import java.util.UUID
-import javax.validation.constraints.NotEmpty
 
 @ExtendWith(SpringExtension::class)
 @WebMvcTest
@@ -53,17 +54,17 @@ open class ResourceSnippetIntegrationTest {
                 @PathVariable otherId: Int?,
                 @RequestHeader("X-Custom-Header") customHeader: String,
                 @RequestBody testDataHolder: TestDataHolder
-            ): ResponseEntity<Resource<TestDataHolder>> {
-                val resource = Resource(testDataHolder.copy(id = UUID.randomUUID().toString()))
-                val link = BasicLinkBuilder.linkToCurrentMapping().slash("some").slash(someId).slash("other").slash(otherId).toUri().toString()
-                resource.add(Link(link, Link.REL_SELF))
-                resource.add(Link(link, "multiple"))
-                resource.add(Link(link, "multiple"))
+            ): ResponseEntity<EntityModel<TestDataHolder>> {
+                val resource = EntityModel.of(testDataHolder.copy(id = UUID.randomUUID().toString()))
+                val link = linkToCurrentMapping().slash("some").slash(someId).slash("other").slash(otherId).toUri().toString()
+                resource.add(Link.of(link, IanaLinkRelations.SELF))
+                resource.add(Link.of(link, "multiple"))
+                resource.add(Link.of(link, "multiple"))
 
                 return ResponseEntity
                     .ok()
                     .header("X-Custom-Header", customHeader)
-                    .body<Resource<TestDataHolder>>(resource)
+                    .body<EntityModel<TestDataHolder>>(resource)
             }
         }
     }

restdocs-api-spec-model/src/main/kotlin/com/epages/restdocs/apispec/model/ResourceModel.kt

@@ -37,7 +37,8 @@ data class RequestModel(
     val securityRequirements: SecurityRequirements?,
     val headers: List<HeaderDescriptor>,
     val pathParameters: List<ParameterDescriptor>,
-    val requestParameters: List<ParameterDescriptor>,
+    val queryParameters: List<ParameterDescriptor>,
+    val formParameters: List<ParameterDescriptor>,
     val requestFields: List<FieldDescriptor>,
     val example: String? = null,
     val schema: Schema? = null

restdocs-api-spec-openapi-generator/src/main/kotlin/com/epages/restdocs/apispec/openapi2/OpenApi20Generator.kt

@@ -288,14 +288,12 @@ object OpenApi20Generator {
                     firstModelForPathAndMethod
                 ).plus(
                     modelsWithSamePathAndMethod
-                        .filter { it.request.contentType != "application/x-www-form-urlencoded" }
-                        .flatMap { it.request.requestParameters }
+                        .flatMap { it.request.queryParameters }
                         .distinctBy { it.name }
                         .map { requestParameterDescriptor2QueryParameter(it) }
                 ).plus(
                     modelsWithSamePathAndMethod
-                        .filter { it.request.contentType == "application/x-www-form-urlencoded" }
-                        .flatMap { it.request.requestParameters }
+                        .flatMap { it.request.formParameters }
                         .distinctBy { it.name }
                         .map { requestParameterDescriptor2FormParameter(it) }
                 ).plus(
@@ -327,6 +325,7 @@ object OpenApi20Generator {
                     SecurityType.OAUTH2 -> addSecurity(OAUTH2_SECURITY_NAME, securityRequirements2ScopesList(securityRequirements))
                     SecurityType.BASIC -> addSecurity(BASIC_SECURITY_NAME, null)
                     SecurityType.API_KEY -> addSecurity(API_KEY_SECURITY_NAME, null)
+                    SecurityType.JWT_BEARER -> { /* not specified for OpenApi 2.0 */ }
                 }
             }
         }