Skip to content

Commit faf25c1

Browse files
author
Corneil du Plessis
committed
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 spring-attic#6008
1 parent 78085ce commit faf25c1

File tree

18 files changed

+303
-201
lines changed

18 files changed

+303
-201
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-33
Original file line numberDiff line numberDiff line change
@@ -114,10 +114,10 @@ void listJobExecutions() throws Exception {
114114
.andDo(print())
115115
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
116116
queryParameters(
117-
parameterWithName("page")
118-
.description("The zero-based page number (optional)"),
119-
parameterWithName("size")
120-
.description("The requested page size (optional)")),
117+
parameterWithName("page").optional()
118+
.description("The zero-based page number"),
119+
parameterWithName("size").optional()
120+
.description("The requested page size")),
121121
responseFields(
122122
subsectionWithPath("_embedded.jobExecutionResourceList")
123123
.description("Contains a collection of Job Executions/"),
@@ -135,10 +135,10 @@ void listThinJobExecutions() throws Exception {
135135
.andDo(print())
136136
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
137137
queryParameters(
138-
parameterWithName("page")
139-
.description("The zero-based page number (optional)"),
140-
parameterWithName("size")
141-
.description("The requested page size (optional)")),
138+
parameterWithName("page").optional()
139+
.description("The zero-based page number"),
140+
parameterWithName("size").optional()
141+
.description("The requested page size")),
142142
responseFields(
143143
subsectionWithPath("_embedded.jobExecutionThinResourceList")
144144
.description("Contains a collection of Job Executions without step executions included/"),
@@ -157,10 +157,10 @@ void listThinJobExecutionsByJobInstanceId() throws Exception {
157157
.andDo(print())
158158
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
159159
queryParameters(
160-
parameterWithName("page")
161-
.description("The zero-based page number (optional)"),
162-
parameterWithName("size")
163-
.description("The requested page size (optional)"),
160+
parameterWithName("page").optional()
161+
.description("The zero-based page number"),
162+
parameterWithName("size").optional()
163+
.description("The requested page size"),
164164
parameterWithName("jobInstanceId")
165165
.description("Filter result by the job instance id")),
166166
responseFields(
@@ -181,10 +181,10 @@ void listThinJobExecutionsByTaskExecutionId() throws Exception {
181181
.andDo(print())
182182
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
183183
queryParameters(
184-
parameterWithName("page")
185-
.description("The zero-based page number (optional)"),
186-
parameterWithName("size")
187-
.description("The requested page size (optional)"),
184+
parameterWithName("page").optional()
185+
.description("The zero-based page number"),
186+
parameterWithName("size").optional()
187+
.description("The requested page size"),
188188
parameterWithName("taskExecutionId")
189189
.description("Filter result by the task execution id")),
190190
responseFields(
@@ -206,10 +206,10 @@ void listThinJobExecutionsByDate() throws Exception {
206206
.andDo(print())
207207
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
208208
queryParameters(
209-
parameterWithName("page")
210-
.description("The zero-based page number (optional)"),
211-
parameterWithName("size")
212-
.description("The requested page size (optional)"),
209+
parameterWithName("page").optional()
210+
.description("The zero-based page number"),
211+
parameterWithName("size").optional()
212+
.description("The requested page size"),
213213
parameterWithName("fromDate")
214214
.description("Filter result from a starting date in the format 'yyyy-MM-dd'T'HH:mm:ss,SSS'"),
215215
parameterWithName("toDate")
@@ -232,10 +232,10 @@ void listJobExecutionsByName() throws Exception {
232232
.andDo(print())
233233
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
234234
queryParameters(
235-
parameterWithName("page")
236-
.description("The zero-based page number (optional)"),
237-
parameterWithName("size")
238-
.description("The requested page size (optional)"),
235+
parameterWithName("page").optional()
236+
.description("The zero-based page number"),
237+
parameterWithName("size").optional()
238+
.description("The requested page size"),
239239
parameterWithName("name")
240240
.description("The name associated with the job execution")),
241241
responseFields(
@@ -256,10 +256,10 @@ void listThinJobExecutionsByName() throws Exception {
256256
.andDo(print())
257257
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
258258
queryParameters(
259-
parameterWithName("page")
260-
.description("The zero-based page number (optional)"),
261-
parameterWithName("size")
262-
.description("The requested page size (optional)"),
259+
parameterWithName("page").optional()
260+
.description("The zero-based page number"),
261+
parameterWithName("size").optional()
262+
.description("The requested page size"),
263263
parameterWithName("name")
264264
.description("The name associated with the job execution")),
265265
responseFields(
@@ -278,7 +278,7 @@ void jobDisplayDetail() throws Exception {
278278
.andExpect(status().isOk())
279279
.andDo(this.documentationHandler.document(
280280
pathParameters(
281-
parameterWithName("id").description("The id of an existing job execution (required)")
281+
parameterWithName("id").description("The id of an existing job execution")
282282
),
283283
responseFields(
284284
fieldWithPath("executionId").description("The execution ID of the job execution"),
@@ -313,9 +313,9 @@ void jobStop() throws Exception {
313313
.andExpect(status().isOk())
314314
.andDo(this.documentationHandler.document(
315315
pathParameters(parameterWithName("id")
316-
.description("The id of an existing job execution (required)"))
316+
.description("The id of an existing job execution"))
317317
, queryParameters(
318-
parameterWithName("stop")
318+
parameterWithName("stop").optional()
319319
.description("Sends signal to stop the job if set to true"))));
320320
}
321321

@@ -328,12 +328,12 @@ void jobRestart() throws Exception {
328328
.andExpect(status().isOk())
329329
.andDo(this.documentationHandler.document(
330330
pathParameters(parameterWithName("id")
331-
.description("The id of an existing job execution (required)"))
331+
.description("The id of an existing job execution"))
332332
, queryParameters(
333333
parameterWithName("useJsonJobParameters").description("If true dataflow will " +
334334
"serialize job parameters as JSON. Default is null, and the default " +
335335
"configuration will be used to determine serialization method.").optional(),
336-
parameterWithName("restart")
336+
parameterWithName("restart").optional()
337337
.description("Sends signal to restart the job if set to true")
338338
)
339339
)

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

+5-5
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(
@@ -102,7 +102,7 @@ void jobDisplayDetail() throws Exception {
102102
.andExpect(status().isOk())
103103
.andDo(this.documentationHandler.document(
104104
pathParameters(
105-
parameterWithName("id").description("The id of an existing job instance (required)")
105+
parameterWithName("id").description("The id of an existing job instance")
106106
),
107107
responseFields(
108108
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)