Skip to content
This repository was archived by the owner on May 14, 2025. It is now read-only.

Commit d2a77ef

Browse files
author
Corneil du Plessis
authored
Fix rest documentation for changes to spring-rest-docs (#6012)
* Fix rest documentation for changes to spring-rest-docs Update request-parameters to query-parameters Added optional where applicable Added snippet template to query-parameters and updated template for path-parameters to improve readability. Fixes #6008 * Update from review Fixed missing optional Removed print()
1 parent f938390 commit d2a77ef

File tree

18 files changed

+303
-217
lines changed

18 files changed

+303
-217
lines changed

‎spring-cloud-dataflow-classic-docs/src/test/java/org/springframework/cloud/dataflow/server/rest/documentation/AppRegistryDocumentation.java

+13-11
Original file line numberDiff line numberDiff line change
@@ -78,8 +78,8 @@ void registeringAnApplicationVersion() throws Exception {
7878
.andDo(
7979
this.documentationHandler.document(
8080
pathParameters(
81-
parameterWithName("type")
82-
.description("The type of application to register. One of " + Arrays.asList(ApplicationType.values()) + " (optional)"),
81+
parameterWithName("type").optional()
82+
.description("The type of application to register. One of " + Arrays.asList(ApplicationType.values())),
8383
parameterWithName("name").description("The name of the application to register"),
8484
parameterWithName("version").description("The version of the application to register")
8585
),
@@ -101,8 +101,9 @@ void registeringAnApplicationVersion() throws Exception {
101101
void bulkRegisteringApps() throws Exception {
102102
this.mockMvc.perform(
103103
post("/apps")
104-
.param("apps", "source.http=maven://org.springframework.cloud.stream.app:http-source-rabbit:4.0.0")
105-
.param("force", "false"))
104+
.queryParam("apps", "source.http=maven://org.springframework.cloud.stream.app:http-source-rabbit:4.0.0")
105+
.queryParam("force", "false")
106+
)
106107
.andExpect(status().isCreated())
107108
.andDo(
108109
this.documentationHandler.document(
@@ -132,13 +133,14 @@ void getApplicationsFiltered() throws Exception {
132133
.andExpect(status().isOk())
133134
.andDo(this.documentationHandler.document(
134135
queryParameters(
135-
parameterWithName("search").description("The search string performed on the name (optional)"),
136+
parameterWithName("search").optional()
137+
.description("The search string performed on the name"),
136138
parameterWithName("type")
137139
.description("Restrict the returned apps to the type of the app. One of " + Arrays.asList(ApplicationType.values())),
138-
parameterWithName("defaultVersion").description("The boolean flag to set to retrieve only the apps of the default versions (optional)"),
139-
parameterWithName("page").description("The zero-based page number (optional)"),
140-
parameterWithName("sort").description("The sort on the list (optional)"),
141-
parameterWithName("size").description("The requested page size (optional)")
140+
parameterWithName("defaultVersion").optional().description("The boolean flag to set to retrieve only the apps of the default versions"),
141+
parameterWithName("page").optional().description("The zero-based page number"),
142+
parameterWithName("sort").optional().description("The sort on the list"),
143+
parameterWithName("size").optional().description("The requested page size")
142144
),
143145
responseFields(
144146
subsectionWithPath("_embedded.appRegistrationResourceList")
@@ -192,7 +194,7 @@ void getSingleApplication() throws Exception {
192194
void registeringAnApplication() throws Exception {
193195
this.mockMvc.perform(
194196
post("/apps/{type}/{name}", ApplicationType.source, "http")
195-
.queryParam("uri", "maven://org.springframework.cloud.stream.app:http-source-rabbit:5.0.0")
197+
.queryParam("uri", "maven://org.springframework.cloud.stream.app:http-source-rabbit:5.0.0")
196198
)
197199
.andExpect(status().isCreated())
198200
.andDo(
@@ -224,7 +226,7 @@ void unregisteringAnApplication() throws Exception {
224226
pathParameters(
225227
parameterWithName("type").description("The type of application to unregister. One of " + Arrays.asList(ApplicationType.values())),
226228
parameterWithName("name").description("The name of the application to unregister"),
227-
parameterWithName("version").description("The version of the application to unregister (optional)")
229+
parameterWithName("version").optional().description("The version of the application to unregister")
228230
)
229231
)
230232
);

‎spring-cloud-dataflow-classic-docs/src/test/java/org/springframework/cloud/dataflow/server/rest/documentation/AuditRecordsDocumentation.java

+10-10
Original file line numberDiff line numberDiff line change
@@ -74,14 +74,14 @@ void listAllAuditRecords() throws Exception {
7474
.andExpect(status().isOk())
7575
.andDo(this.documentationHandler.document(
7676
queryParameters(
77-
parameterWithName("page").description("The zero-based page number (optional)"),
78-
parameterWithName("size").description("The requested page size (optional)"),
79-
parameterWithName("operations").description("Comma-separated list of Audit Operations (optional)"),
80-
parameterWithName("actions").description("Comma-separated list of Audit Actions (optional)"),
81-
parameterWithName("fromDate")
82-
.description("From date filter (ex.: 2019-02-03T00:00:30) (optional)"),
83-
parameterWithName("toDate")
84-
.description("To date filter (ex.: 2019-02-03T00:00:30) (optional)")
77+
parameterWithName("page").optional().description("The zero-based page number"),
78+
parameterWithName("size").optional().description("The requested page size"),
79+
parameterWithName("operations").optional().description("Comma-separated list of Audit Operations"),
80+
parameterWithName("actions").optional().description("Comma-separated list of Audit Actions"),
81+
parameterWithName("fromDate").optional()
82+
.description("From date filter (ex.: 2019-02-03T00:00:30)"),
83+
parameterWithName("toDate").optional()
84+
.description("To date filter (ex.: 2019-02-03T00:00:30)")
8585
),
8686
responseFields(
8787
subsectionWithPath("_embedded.auditRecordResourceList")
@@ -97,11 +97,11 @@ void getAuditRecord() throws Exception {
9797
.andExpect(status().isOk())
9898
.andDo(this.documentationHandler.document(
9999
pathParameters(
100-
parameterWithName("id").description("The id of the audit record to query (required)")
100+
parameterWithName("id").description("The id of the audit record to query")
101101
),
102102
responseFields(
103103
fieldWithPath("auditRecordId").description("The id of the audit record"),
104-
fieldWithPath("createdBy").description("The author of the audit record (optional)"),
104+
fieldWithPath("createdBy").optional().description("The author of the audit record"),
105105
fieldWithPath("correlationId").description("The correlation ID of the audit record"),
106106
fieldWithPath("auditData").description("The data of the audit record"),
107107
fieldWithPath("createdOn").description("The creation date of the audit record"),

‎spring-cloud-dataflow-classic-docs/src/test/java/org/springframework/cloud/dataflow/server/rest/documentation/JobExecutionsDocumentation.java

+33-40
Original file line numberDiff line numberDiff line change
@@ -111,13 +111,12 @@ void listJobExecutions() throws Exception {
111111
get("/jobs/executions")
112112
.queryParam("page", "0")
113113
.queryParam("size", "10"))
114-
.andDo(print())
115114
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
116115
queryParameters(
117-
parameterWithName("page")
118-
.description("The zero-based page number (optional)"),
119-
parameterWithName("size")
120-
.description("The requested page size (optional)")),
116+
parameterWithName("page").optional()
117+
.description("The zero-based page number"),
118+
parameterWithName("size").optional()
119+
.description("The requested page size")),
121120
responseFields(
122121
subsectionWithPath("_embedded.jobExecutionResourceList")
123122
.description("Contains a collection of Job Executions/"),
@@ -132,13 +131,12 @@ void listThinJobExecutions() throws Exception {
132131
get("/jobs/thinexecutions")
133132
.queryParam("page", "0")
134133
.queryParam("size", "10"))
135-
.andDo(print())
136134
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
137135
queryParameters(
138-
parameterWithName("page")
139-
.description("The zero-based page number (optional)"),
140-
parameterWithName("size")
141-
.description("The requested page size (optional)")),
136+
parameterWithName("page").optional()
137+
.description("The zero-based page number"),
138+
parameterWithName("size").optional()
139+
.description("The requested page size")),
142140
responseFields(
143141
subsectionWithPath("_embedded.jobExecutionThinResourceList")
144142
.description("Contains a collection of Job Executions without step executions included/"),
@@ -154,13 +152,12 @@ void listThinJobExecutionsByJobInstanceId() throws Exception {
154152
.queryParam("page", "0")
155153
.queryParam("size", "10")
156154
.queryParam("jobInstanceId", "1"))
157-
.andDo(print())
158155
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
159156
queryParameters(
160-
parameterWithName("page")
161-
.description("The zero-based page number (optional)"),
162-
parameterWithName("size")
163-
.description("The requested page size (optional)"),
157+
parameterWithName("page").optional()
158+
.description("The zero-based page number"),
159+
parameterWithName("size").optional()
160+
.description("The requested page size"),
164161
parameterWithName("jobInstanceId")
165162
.description("Filter result by the job instance id")),
166163
responseFields(
@@ -178,13 +175,12 @@ void listThinJobExecutionsByTaskExecutionId() throws Exception {
178175
.queryParam("page", "0")
179176
.queryParam("size", "10")
180177
.queryParam("taskExecutionId", "1"))
181-
.andDo(print())
182178
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
183179
queryParameters(
184-
parameterWithName("page")
185-
.description("The zero-based page number (optional)"),
186-
parameterWithName("size")
187-
.description("The requested page size (optional)"),
180+
parameterWithName("page").optional()
181+
.description("The zero-based page number"),
182+
parameterWithName("size").optional()
183+
.description("The requested page size"),
188184
parameterWithName("taskExecutionId")
189185
.description("Filter result by the task execution id")),
190186
responseFields(
@@ -203,13 +199,12 @@ void listThinJobExecutionsByDate() throws Exception {
203199
.queryParam("size", "10")
204200
.queryParam("fromDate", "2000-09-24T17:00:45,000")
205201
.queryParam("toDate", "2050-09-24T18:00:45,000"))
206-
.andDo(print())
207202
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
208203
queryParameters(
209-
parameterWithName("page")
210-
.description("The zero-based page number (optional)"),
211-
parameterWithName("size")
212-
.description("The requested page size (optional)"),
204+
parameterWithName("page").optional()
205+
.description("The zero-based page number"),
206+
parameterWithName("size").optional()
207+
.description("The requested page size"),
213208
parameterWithName("fromDate")
214209
.description("Filter result from a starting date in the format 'yyyy-MM-dd'T'HH:mm:ss,SSS'"),
215210
parameterWithName("toDate")
@@ -229,13 +224,12 @@ void listJobExecutionsByName() throws Exception {
229224
.queryParam("name", JOB_NAME)
230225
.queryParam("page", "0")
231226
.queryParam("size", "10"))
232-
.andDo(print())
233227
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
234228
queryParameters(
235-
parameterWithName("page")
236-
.description("The zero-based page number (optional)"),
237-
parameterWithName("size")
238-
.description("The requested page size (optional)"),
229+
parameterWithName("page").optional()
230+
.description("The zero-based page number"),
231+
parameterWithName("size").optional()
232+
.description("The requested page size"),
239233
parameterWithName("name")
240234
.description("The name associated with the job execution")),
241235
responseFields(
@@ -253,13 +247,12 @@ void listThinJobExecutionsByName() throws Exception {
253247
.queryParam("name", JOB_NAME)
254248
.queryParam("page", "0")
255249
.queryParam("size", "10"))
256-
.andDo(print())
257250
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
258251
queryParameters(
259-
parameterWithName("page")
260-
.description("The zero-based page number (optional)"),
261-
parameterWithName("size")
262-
.description("The requested page size (optional)"),
252+
parameterWithName("page").optional()
253+
.description("The zero-based page number"),
254+
parameterWithName("size").optional()
255+
.description("The requested page size"),
263256
parameterWithName("name")
264257
.description("The name associated with the job execution")),
265258
responseFields(
@@ -278,7 +271,7 @@ void jobDisplayDetail() throws Exception {
278271
.andExpect(status().isOk())
279272
.andDo(this.documentationHandler.document(
280273
pathParameters(
281-
parameterWithName("id").description("The id of an existing job execution (required)")
274+
parameterWithName("id").description("The id of an existing job execution")
282275
),
283276
responseFields(
284277
fieldWithPath("executionId").description("The execution ID of the job execution"),
@@ -313,9 +306,9 @@ void jobStop() throws Exception {
313306
.andExpect(status().isOk())
314307
.andDo(this.documentationHandler.document(
315308
pathParameters(parameterWithName("id")
316-
.description("The id of an existing job execution (required)"))
309+
.description("The id of an existing job execution"))
317310
, queryParameters(
318-
parameterWithName("stop")
311+
parameterWithName("stop").optional()
319312
.description("Sends signal to stop the job if set to true"))));
320313
}
321314

@@ -328,12 +321,12 @@ void jobRestart() throws Exception {
328321
.andExpect(status().isOk())
329322
.andDo(this.documentationHandler.document(
330323
pathParameters(parameterWithName("id")
331-
.description("The id of an existing job execution (required)"))
324+
.description("The id of an existing job execution"))
332325
, queryParameters(
333326
parameterWithName("useJsonJobParameters").description("If true dataflow will " +
334327
"serialize job parameters as JSON. Default is null, and the default " +
335328
"configuration will be used to determine serialization method.").optional(),
336-
parameterWithName("restart")
329+
parameterWithName("restart").optional()
337330
.description("Sends signal to restart the job if set to true")
338331
)
339332
)

‎spring-cloud-dataflow-classic-docs/src/test/java/org/springframework/cloud/dataflow/server/rest/documentation/JobInstancesDocumentation.java

+5-6
Original file line numberDiff line numberDiff line change
@@ -81,10 +81,10 @@ void listJobInstances() throws Exception {
8181
.param("size", "10"))
8282
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
8383
queryParameters(
84-
parameterWithName("page")
85-
.description("The zero-based page number (optional)"),
86-
parameterWithName("size")
87-
.description("The requested page size (optional)"),
84+
parameterWithName("page").optional()
85+
.description("The zero-based page number"),
86+
parameterWithName("size").optional()
87+
.description("The requested page size"),
8888
parameterWithName("name")
8989
.description("The name associated with the job instance")),
9090
responseFields(
@@ -98,11 +98,10 @@ void listJobInstances() throws Exception {
9898
void jobDisplayDetail() throws Exception {
9999
this.mockMvc.perform(
100100
get("/jobs/instances/{id}", "1"))
101-
.andDo(print())
102101
.andExpect(status().isOk())
103102
.andDo(this.documentationHandler.document(
104103
pathParameters(
105-
parameterWithName("id").description("The id of an existing job instance (required)")
104+
parameterWithName("id").description("The id of an existing job instance")
106105
),
107106
responseFields(
108107
fieldWithPath("jobName").description("The name of the job instance"),

‎spring-cloud-dataflow-classic-docs/src/test/java/org/springframework/cloud/dataflow/server/rest/documentation/JobStepExecutionsDocumentation.java

+9-9
Original file line numberDiff line numberDiff line change
@@ -90,12 +90,12 @@ void listStepExecutionsForJob() throws Exception {
9090
.param("size", "10"))
9191
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
9292
queryParameters(
93-
parameterWithName("page")
94-
.description("The zero-based page number (optional)"),
95-
parameterWithName("size")
96-
.description("The requested page size (optional)")),
93+
parameterWithName("page").optional()
94+
.description("The zero-based page number"),
95+
parameterWithName("size").optional()
96+
.description("The requested page size")),
9797
pathParameters(parameterWithName("id")
98-
.description("The id of an existing job execution (required)")),
98+
.description("The id of an existing job execution")),
9999
responseFields(
100100
subsectionWithPath("_embedded.stepExecutionResourceList")
101101
.description("Contains a collection of Step Executions/"),
@@ -109,9 +109,9 @@ void stepDetail() throws Exception {
109109
get("/jobs/executions/{id}/steps/{stepid}", "1", "1"))
110110
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
111111
pathParameters(
112-
parameterWithName("id").description("The id of an existing job execution (required)"),
112+
parameterWithName("id").description("The id of an existing job execution"),
113113
parameterWithName("stepid")
114-
.description("The id of an existing step execution for a specific job execution (required)")
114+
.description("The id of an existing step execution for a specific job execution")
115115
),
116116
responseFields(
117117
fieldWithPath("jobExecutionId").description("The ID of the job step execution"),
@@ -129,9 +129,9 @@ void stepProgress() throws Exception {
129129
get("/jobs/executions/{id}/steps/{stepid}/progress", "1", "1"))
130130
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
131131
pathParameters(
132-
parameterWithName("id").description("The id of an existing job execution (required)"),
132+
parameterWithName("id").description("The id of an existing job execution"),
133133
parameterWithName("stepid")
134-
.description("The id of an existing step execution for a specific job execution (required)")
134+
.description("The id of an existing step execution for a specific job execution")
135135
),
136136
responseFields(
137137
subsectionWithPath("stepExecution").description("The detailed step details of the job step execution"),

0 commit comments

Comments
 (0)