Skip to content

Commit 415f402

Browse files
tobiaskrausstobiaskrauss
committed
Support Spring REST Docs 3.0.0 (ePages-de#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
1 parent 9b84729 commit 415f402

File tree

22 files changed

+268
-110
lines changed

22 files changed

+268
-110
lines changed

‎build.gradle.kts

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ plugins {
1212
id("pl.allegro.tech.build.axion-release") version "1.9.2"
1313
jacoco
1414
java
15-
kotlin("jvm") version "1.4.20" apply false
15+
kotlin("jvm") version "1.7.10" apply false
1616
`maven-publish`
1717
}
1818

@@ -58,12 +58,12 @@ allprojects {
5858
subprojects {
5959

6060
val jacksonVersion by extra { "2.12.2" }
61-
val springBootVersion by extra { "2.1.9.RELEASE" }
62-
val springRestDocsVersion by extra { "2.0.4.RELEASE" }
61+
val springBootVersion by extra { "3.0.2" }
62+
val springRestDocsVersion by extra { "3.0.0" }
6363
val junitVersion by extra { "5.4.2" }
6464

6565
tasks.withType<KotlinCompile> {
66-
kotlinOptions.jvmTarget = "1.8"
66+
kotlinOptions.jvmTarget = "17"
6767
}
6868

6969
tasks.withType<Test> {

‎gradle/wrapper/gradle-wrapper.jar

1.71 KB
Binary file not shown.

‎gradle/wrapper/gradle-wrapper.properties

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
distributionBase=GRADLE_USER_HOME
22
distributionPath=wrapper/dists
3-
distributionUrl=https\://services.gradle.org/distributions/gradle-7.4.2-all.zip
3+
distributionUrl=https\://services.gradle.org/distributions/gradle-7.6-all.zip
4+
networkTimeout=10000
45
zipStoreBase=GRADLE_USER_HOME
56
zipStorePath=wrapper/dists

‎gradlew

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@
5555
# Darwin, MinGW, and NonStop.
5656
#
5757
# (3) This script is generated from the Groovy template
58-
# https://github.com/gradle/gradle/blob/master/subprojects/plugins/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
58+
# https://github.com/gradle/gradle/blob/HEAD/subprojects/plugins/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
5959
# within the Gradle project.
6060
#
6161
# You can find Gradle at https://github.com/gradle/gradle/.
@@ -80,10 +80,10 @@ do
8080
esac
8181
done
8282

83-
APP_HOME=$( cd "${APP_HOME:-./}" && pwd -P ) || exit
84-
85-
APP_NAME="Gradle"
83+
# This is normally unused
84+
# shellcheck disable=SC2034
8685
APP_BASE_NAME=${0##*/}
86+
APP_HOME=$( cd "${APP_HOME:-./}" && pwd -P ) || exit
8787

8888
# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
8989
DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
@@ -143,12 +143,16 @@ fi
143143
if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
144144
case $MAX_FD in #(
145145
max*)
146+
# In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.
147+
# shellcheck disable=SC3045
146148
MAX_FD=$( ulimit -H -n ) ||
147149
warn "Could not query maximum file descriptor limit"
148150
esac
149151
case $MAX_FD in #(
150152
'' | soft) :;; #(
151153
*)
154+
# In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.
155+
# shellcheck disable=SC3045
152156
ulimit -n "$MAX_FD" ||
153157
warn "Could not set maximum file descriptor limit to $MAX_FD"
154158
esac
@@ -205,6 +209,12 @@ set -- \
205209
org.gradle.wrapper.GradleWrapperMain \
206210
"$@"
207211

212+
# Stop when "xargs" is not available.
213+
if ! command -v xargs >/dev/null 2>&1
214+
then
215+
die "xargs is not available"
216+
fi
217+
208218
# Use "xargs" to parse quoted args.
209219
#
210220
# With -n1 it outputs one arg per line, with the quotes and backslashes removed.

‎gradlew.bat

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
@rem limitations under the License.
1515
@rem
1616

17-
@if "%DEBUG%" == "" @echo off
17+
@if "%DEBUG%"=="" @echo off
1818
@rem ##########################################################################
1919
@rem
2020
@rem Gradle startup script for Windows
@@ -25,7 +25,8 @@
2525
if "%OS%"=="Windows_NT" setlocal
2626

2727
set DIRNAME=%~dp0
28-
if "%DIRNAME%" == "" set DIRNAME=.
28+
if "%DIRNAME%"=="" set DIRNAME=.
29+
@rem This is normally unused
2930
set APP_BASE_NAME=%~n0
3031
set APP_HOME=%DIRNAME%
3132

@@ -40,7 +41,7 @@ if defined JAVA_HOME goto findJavaFromJavaHome
4041

4142
set JAVA_EXE=java.exe
4243
%JAVA_EXE% -version >NUL 2>&1
43-
if "%ERRORLEVEL%" == "0" goto execute
44+
if %ERRORLEVEL% equ 0 goto execute
4445

4546
echo.
4647
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
7576

7677
:end
7778
@rem End local scope for the variables with windows NT shell
78-
if "%ERRORLEVEL%"=="0" goto mainEnd
79+
if %ERRORLEVEL% equ 0 goto mainEnd
7980

8081
:fail
8182
rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
8283
rem the _cmd.exe /c_ return code!
83-
if not "" == "%GRADLE_EXIT_CONSOLE%" exit 1
84-
exit /b 1
84+
set EXIT_CODE=%ERRORLEVEL%
85+
if %EXIT_CODE% equ 0 set EXIT_CODE=1
86+
if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE%
87+
exit /b %EXIT_CODE%
8588

8689
:mainEnd
8790
if "%OS%"=="Windows_NT" endlocal

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ dependencies {
2020
testImplementation("org.springframework.boot:spring-boot-starter-test:$springBootVersion") {
2121
exclude("junit")
2222
}
23+
testImplementation("org.springframework.boot:spring-boot-starter-validation:$springBootVersion")
2324
testImplementation("org.junit.jupiter:junit-jupiter-engine:$junitVersion")
2425
testImplementation("org.junit-pioneer:junit-pioneer:0.3.0")
2526
testImplementation("org.springframework.boot:spring-boot-starter-hateoas:$springBootVersion")

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

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,18 @@ package com.epages.restdocs.apispec
22

33
import com.epages.restdocs.apispec.ResourceDocumentation.parameterWithName
44
import com.epages.restdocs.apispec.ResourceDocumentation.resource
5+
import jakarta.validation.constraints.NotEmpty
56
import org.hibernate.validator.constraints.Length
67
import org.junit.jupiter.api.extension.ExtendWith
78
import org.springframework.boot.SpringApplication
89
import org.springframework.boot.autoconfigure.SpringBootApplication
910
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs
1011
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest
1112
import org.springframework.context.ConfigurableApplicationContext
13+
import org.springframework.hateoas.EntityModel
14+
import org.springframework.hateoas.IanaLinkRelations
1215
import org.springframework.hateoas.Link
13-
import org.springframework.hateoas.Resource
14-
import org.springframework.hateoas.mvc.BasicLinkBuilder
16+
import org.springframework.hateoas.server.mvc.BasicLinkBuilder.linkToCurrentMapping
1517
import org.springframework.http.HttpHeaders.ACCEPT
1618
import org.springframework.http.HttpHeaders.CONTENT_TYPE
1719
import org.springframework.http.ResponseEntity
@@ -26,7 +28,6 @@ import org.springframework.web.bind.annotation.RequestBody
2628
import org.springframework.web.bind.annotation.RequestHeader
2729
import org.springframework.web.bind.annotation.RestController
2830
import java.util.UUID
29-
import javax.validation.constraints.NotEmpty
3031

3132
@ExtendWith(SpringExtension::class)
3233
@WebMvcTest
@@ -53,17 +54,17 @@ open class ResourceSnippetIntegrationTest {
5354
@PathVariable otherId: Int?,
5455
@RequestHeader("X-Custom-Header") customHeader: String,
5556
@RequestBody testDataHolder: TestDataHolder
56-
): ResponseEntity<Resource<TestDataHolder>> {
57-
val resource = Resource(testDataHolder.copy(id = UUID.randomUUID().toString()))
58-
val link = BasicLinkBuilder.linkToCurrentMapping().slash("some").slash(someId).slash("other").slash(otherId).toUri().toString()
59-
resource.add(Link(link, Link.REL_SELF))
60-
resource.add(Link(link, "multiple"))
61-
resource.add(Link(link, "multiple"))
57+
): ResponseEntity<EntityModel<TestDataHolder>> {
58+
val resource = EntityModel.of(testDataHolder.copy(id = UUID.randomUUID().toString()))
59+
val link = linkToCurrentMapping().slash("some").slash(someId).slash("other").slash(otherId).toUri().toString()
60+
resource.add(Link.of(link, IanaLinkRelations.SELF))
61+
resource.add(Link.of(link, "multiple"))
62+
resource.add(Link.of(link, "multiple"))
6263

6364
return ResponseEntity
6465
.ok()
6566
.header("X-Custom-Header", customHeader)
66-
.body<Resource<TestDataHolder>>(resource)
67+
.body<EntityModel<TestDataHolder>>(resource)
6768
}
6869
}
6970
}

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -327,6 +327,7 @@ object OpenApi20Generator {
327327
SecurityType.OAUTH2 -> addSecurity(OAUTH2_SECURITY_NAME, securityRequirements2ScopesList(securityRequirements))
328328
SecurityType.BASIC -> addSecurity(BASIC_SECURITY_NAME, null)
329329
SecurityType.API_KEY -> addSecurity(API_KEY_SECURITY_NAME, null)
330+
SecurityType.JWT_BEARER -> { /* not specified for OpenApi 2.0 */ }
330331
}
331332
}
332333
}

‎restdocs-api-spec-restassured/build.gradle.kts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ dependencies {
2121
}
2222
testImplementation("org.junit.jupiter:junit-jupiter-engine:$junitVersion")
2323
testImplementation("org.junit-pioneer:junit-pioneer:0.3.0")
24+
testImplementation("org.springframework.boot:spring-boot-starter-validation:$springBootVersion")
2425
testImplementation("org.springframework.boot:spring-boot-starter-hateoas:$springBootVersion")
2526
}
2627

‎restdocs-api-spec-restassured/src/main/kotlin/com/epages/restdocs/apispec/RestAssuredRestDocumentationWrapper.kt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@ package com.epages.restdocs.apispec
22

33
import org.springframework.restdocs.operation.preprocess.OperationRequestPreprocessor
44
import org.springframework.restdocs.operation.preprocess.OperationResponsePreprocessor
5-
import org.springframework.restdocs.restassured3.RestAssuredRestDocumentation
6-
import org.springframework.restdocs.restassured3.RestDocumentationFilter
5+
import org.springframework.restdocs.restassured.RestAssuredRestDocumentation
6+
import org.springframework.restdocs.restassured.RestDocumentationFilter
77
import org.springframework.restdocs.snippet.Snippet
88
import java.util.function.Function
99

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

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ package com.epages.restdocs.apispec
22

33
import com.epages.restdocs.apispec.ResourceDocumentation.parameterWithName
44
import com.epages.restdocs.apispec.ResourceDocumentation.resource
5+
import jakarta.validation.constraints.NotEmpty
56
import org.hibernate.validator.constraints.Length
67
import org.junit.jupiter.api.AfterEach
78
import org.junit.jupiter.api.BeforeEach
@@ -11,9 +12,10 @@ import org.springframework.boot.autoconfigure.SpringBootApplication
1112
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs
1213
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest
1314
import org.springframework.context.ConfigurableApplicationContext
15+
import org.springframework.hateoas.EntityModel
16+
import org.springframework.hateoas.IanaLinkRelations
1417
import org.springframework.hateoas.Link
15-
import org.springframework.hateoas.Resource
16-
import org.springframework.hateoas.mvc.BasicLinkBuilder
18+
import org.springframework.hateoas.server.mvc.BasicLinkBuilder.linkToCurrentMapping
1719
import org.springframework.http.HttpHeaders.ACCEPT
1820
import org.springframework.http.HttpHeaders.CONTENT_TYPE
1921
import org.springframework.http.ResponseEntity
@@ -29,7 +31,6 @@ import org.springframework.web.bind.annotation.RequestBody
2931
import org.springframework.web.bind.annotation.RequestHeader
3032
import org.springframework.web.bind.annotation.RestController
3133
import java.util.UUID
32-
import javax.validation.constraints.NotEmpty
3334

3435
@ExtendWith(SpringExtension::class)
3536
@WebMvcTest
@@ -71,17 +72,17 @@ open class ResourceSnippetIntegrationTest {
7172
@PathVariable otherId: Int?,
7273
@RequestHeader("X-Custom-Header") customHeader: String,
7374
@RequestBody testDataHolder: TestDataHolder
74-
): ResponseEntity<Resource<TestDataHolder>> {
75-
val resource = Resource(testDataHolder.copy(id = UUID.randomUUID().toString()))
76-
val link = BasicLinkBuilder.linkToCurrentMapping().slash("some").slash(someId).slash("other").slash(otherId).toUri().toString()
77-
resource.add(Link(link, Link.REL_SELF))
78-
resource.add(Link(link, "multiple"))
79-
resource.add(Link(link, "multiple"))
75+
): ResponseEntity<EntityModel<TestDataHolder>> {
76+
val resource = EntityModel.of(testDataHolder.copy(id = UUID.randomUUID().toString()))
77+
val link = linkToCurrentMapping().slash("some").slash(someId).slash("other").slash(otherId).toUri().toString()
78+
resource.add(Link.of(link, IanaLinkRelations.SELF))
79+
resource.add(Link.of(link, "multiple"))
80+
resource.add(Link.of(link, "multiple"))
8081

8182
return ResponseEntity
8283
.ok()
8384
.header("X-Custom-Header", customHeader)
84-
.body<Resource<TestDataHolder>>(resource)
85+
.body<EntityModel<TestDataHolder>>(resource)
8586
}
8687
}
8788
}

‎restdocs-api-spec-restassured/src/test/kotlin/com/epages/restdocs/apispec/RestAssuredRestDocumentationWrapperIntegrationTest.kt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,8 @@ import org.springframework.restdocs.payload.PayloadDocumentation.responseFields
2525
import org.springframework.restdocs.payload.PayloadDocumentation.subsectionWithPath
2626
import org.springframework.restdocs.request.RequestDocumentation.parameterWithName
2727
import org.springframework.restdocs.request.RequestDocumentation.pathParameters
28-
import org.springframework.restdocs.restassured3.RestAssuredRestDocumentation
29-
import org.springframework.restdocs.restassured3.RestDocumentationFilter
28+
import org.springframework.restdocs.restassured.RestAssuredRestDocumentation
29+
import org.springframework.restdocs.restassured.RestDocumentationFilter
3030
import java.io.File
3131

3232
@ExtendWith(RestDocumentationExtension::class)

‎restdocs-api-spec-webtestclient/build.gradle.kts

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@ dependencies {
2222
testImplementation("org.springframework.boot:spring-boot-starter-test:$springBootVersion") {
2323
exclude("junit")
2424
}
25+
testImplementation("org.hibernate.validator:hibernate-validator:8.0.0.Final")
26+
testImplementation("org.springframework.boot:spring-boot-starter-validation:$springBootVersion")
2527
testImplementation("org.junit.jupiter:junit-jupiter-engine:$junitVersion")
2628
testImplementation("org.junit-pioneer:junit-pioneer:0.3.0")
2729
testImplementation("org.springframework.boot:spring-boot-starter-web:$springBootVersion")

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ package com.epages.restdocs.apispec
22

33
import com.epages.restdocs.apispec.ResourceDocumentation.parameterWithName
44
import com.epages.restdocs.apispec.ResourceDocumentation.resource
5+
import jakarta.validation.constraints.NotEmpty
56
import org.hibernate.validator.constraints.Length
67
import org.junit.jupiter.api.extension.ExtendWith
78
import org.springframework.boot.SpringApplication
@@ -24,7 +25,6 @@ import org.springframework.web.bind.annotation.RequestBody
2425
import org.springframework.web.bind.annotation.RequestHeader
2526
import org.springframework.web.bind.annotation.RestController
2627
import java.util.UUID
27-
import javax.validation.constraints.NotEmpty
2828

2929
@ExtendWith(SpringExtension::class)
3030
@AutoConfigureRestDocs

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@ dependencies {
1818
implementation(kotlin("reflect"))
1919

2020
implementation("org.springframework.restdocs:spring-restdocs-core:$springRestDocsVersion")
21+
implementation("org.springframework.boot:spring-boot-starter-web:$springBootVersion")
22+
implementation("org.springframework.boot:spring-boot-starter-validation:$springBootVersion")
2123
implementation("com.fasterxml.jackson.core:jackson-databind:$jacksonVersion")
2224
implementation("com.fasterxml.jackson.module:jackson-module-kotlin:$jacksonVersion")
2325

‎restdocs-api-spec/src/main/kotlin/com/epages/restdocs/apispec/DescriptorValidator.kt

Lines changed: 25 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,11 @@ import org.springframework.restdocs.payload.FieldDescriptor
1212
import org.springframework.restdocs.payload.JsonFieldType
1313
import org.springframework.restdocs.payload.RequestFieldsSnippet
1414
import org.springframework.restdocs.payload.ResponseFieldsSnippet
15+
import org.springframework.restdocs.request.FormParametersSnippet
1516
import org.springframework.restdocs.request.ParameterDescriptor
1617
import org.springframework.restdocs.request.PathParametersSnippet
18+
import org.springframework.restdocs.request.QueryParametersSnippet
1719
import org.springframework.restdocs.request.RequestDocumentation.parameterWithName
18-
import org.springframework.restdocs.request.RequestParametersSnippet
1920

2021
internal object DescriptorValidator {
2122

@@ -46,14 +47,23 @@ internal object DescriptorValidator {
4647
)
4748
)
4849
}
49-
5050
validateIfDescriptorsPresent(
51-
requestParameters,
51+
queryParameters,
52+
operation
53+
) {
54+
QueryParameterSnippetWrapper(
55+
toParameterDescriptors(
56+
queryParameters
57+
)
58+
)
59+
}
60+
validateIfDescriptorsPresent(
61+
formParameters,
5262
operation
5363
) {
54-
RequestParameterSnippetWrapper(
64+
FormParameterSnippetWrapper(
5565
toParameterDescriptors(
56-
requestParameters
66+
formParameters
5767
)
5868
)
5969
}
@@ -159,8 +169,16 @@ internal object DescriptorValidator {
159169
}
160170
}
161171

162-
private class RequestParameterSnippetWrapper(descriptors: List<ParameterDescriptor>) :
163-
RequestParametersSnippet(descriptors),
172+
private class FormParameterSnippetWrapper(descriptors: List<ParameterDescriptor>) :
173+
FormParametersSnippet(descriptors),
174+
ValidateableSnippet {
175+
override fun validate(operation: Operation) {
176+
super.createModel(operation)
177+
}
178+
}
179+
180+
private class QueryParameterSnippetWrapper(descriptors: List<ParameterDescriptor>) :
181+
QueryParametersSnippet(descriptors),
164182
ValidateableSnippet {
165183
override fun validate(operation: Operation) {
166184
super.createModel(operation)

0 commit comments

Comments
 (0)