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

Author: tobiaskrauss

.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.jar

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

gradle/wrapper/gradle-wrapper.properties

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

gradlew

@@ -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")

gradlew.bat

@@ -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-gradle-plugin/src/test/kotlin/com/epages/restdocs/apispec/gradle/ApiSpecTaskTest.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