Skip to content

Commit

Permalink
Fix rest documentation for changes to spring-rest-docs (#6012)
Browse files Browse the repository at this point in the history 
* 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()
  • Loading branch information
@corneil
corneil authored Oct 28, 2024
1 parent f938390 commit d2a77ef
Show file tree
Hide file tree
Showing 18 changed files with 303 additions and 217 deletions.
24 changes: 13 additions & 11 deletions ...rg/springframework/cloud/dataflow/server/rest/documentation/AppRegistryDocumentation.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,8 +78,8 @@ void registeringAnApplicationVersion() throws Exception {
.andDo(
this.documentationHandler.document(
pathParameters(
parameterWithName("type")
.description("The type of application to register. One of " + Arrays.asList(ApplicationType.values()) + " (optional)"),
parameterWithName("type").optional()
.description("The type of application to register. One of " + Arrays.asList(ApplicationType.values())),
parameterWithName("name").description("The name of the application to register"),
parameterWithName("version").description("The version of the application to register")
),
Expand All @@ -101,8 +101,9 @@ void registeringAnApplicationVersion() throws Exception {
void bulkRegisteringApps() throws Exception {
this.mockMvc.perform(
post("/apps")
.param("apps", "source.http=maven://org.springframework.cloud.stream.app:http-source-rabbit:4.0.0")
.param("force", "false"))
.queryParam("apps", "source.http=maven://org.springframework.cloud.stream.app:http-source-rabbit:4.0.0")
.queryParam("force", "false")
)
.andExpect(status().isCreated())
.andDo(
this.documentationHandler.document(
Expand Down Expand Up @@ -132,13 +133,14 @@ void getApplicationsFiltered() throws Exception {
.andExpect(status().isOk())
.andDo(this.documentationHandler.document(
queryParameters(
parameterWithName("search").description("The search string performed on the name (optional)"),
parameterWithName("search").optional()
.description("The search string performed on the name"),
parameterWithName("type")
.description("Restrict the returned apps to the type of the app. One of " + Arrays.asList(ApplicationType.values())),
parameterWithName("defaultVersion").description("The boolean flag to set to retrieve only the apps of the default versions (optional)"),
parameterWithName("page").description("The zero-based page number (optional)"),
parameterWithName("sort").description("The sort on the list (optional)"),
parameterWithName("size").description("The requested page size (optional)")
parameterWithName("defaultVersion").optional().description("The boolean flag to set to retrieve only the apps of the default versions"),
parameterWithName("page").optional().description("The zero-based page number"),
parameterWithName("sort").optional().description("The sort on the list"),
parameterWithName("size").optional().description("The requested page size")
),
responseFields(
subsectionWithPath("_embedded.appRegistrationResourceList")
Expand Down Expand Up @@ -192,7 +194,7 @@ void getSingleApplication() throws Exception {
void registeringAnApplication() throws Exception {
this.mockMvc.perform(
post("/apps/{type}/{name}", ApplicationType.source, "http")
.queryParam("uri", "maven://org.springframework.cloud.stream.app:http-source-rabbit:5.0.0")
.queryParam("uri", "maven://org.springframework.cloud.stream.app:http-source-rabbit:5.0.0")
)
.andExpect(status().isCreated())
.andDo(
Expand Down Expand Up @@ -224,7 +226,7 @@ void unregisteringAnApplication() throws Exception {
pathParameters(
parameterWithName("type").description("The type of application to unregister. One of " + Arrays.asList(ApplicationType.values())),
parameterWithName("name").description("The name of the application to unregister"),
parameterWithName("version").description("The version of the application to unregister (optional)")
parameterWithName("version").optional().description("The version of the application to unregister")
)
)
);
Expand Down
20 changes: 10 additions & 10 deletions ...g/springframework/cloud/dataflow/server/rest/documentation/AuditRecordsDocumentation.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,14 +74,14 @@ void listAllAuditRecords() throws Exception {
.andExpect(status().isOk())
.andDo(this.documentationHandler.document(
queryParameters(
parameterWithName("page").description("The zero-based page number (optional)"),
parameterWithName("size").description("The requested page size (optional)"),
parameterWithName("operations").description("Comma-separated list of Audit Operations (optional)"),
parameterWithName("actions").description("Comma-separated list of Audit Actions (optional)"),
parameterWithName("fromDate")
.description("From date filter (ex.: 2019-02-03T00:00:30) (optional)"),
parameterWithName("toDate")
.description("To date filter (ex.: 2019-02-03T00:00:30) (optional)")
parameterWithName("page").optional().description("The zero-based page number"),
parameterWithName("size").optional().description("The requested page size"),
parameterWithName("operations").optional().description("Comma-separated list of Audit Operations"),
parameterWithName("actions").optional().description("Comma-separated list of Audit Actions"),
parameterWithName("fromDate").optional()
.description("From date filter (ex.: 2019-02-03T00:00:30)"),
parameterWithName("toDate").optional()
.description("To date filter (ex.: 2019-02-03T00:00:30)")
),
responseFields(
subsectionWithPath("_embedded.auditRecordResourceList")
Expand All @@ -97,11 +97,11 @@ void getAuditRecord() throws Exception {
.andExpect(status().isOk())
.andDo(this.documentationHandler.document(
pathParameters(
parameterWithName("id").description("The id of the audit record to query (required)")
parameterWithName("id").description("The id of the audit record to query")
),
responseFields(
fieldWithPath("auditRecordId").description("The id of the audit record"),
fieldWithPath("createdBy").description("The author of the audit record (optional)"),
fieldWithPath("createdBy").optional().description("The author of the audit record"),
fieldWithPath("correlationId").description("The correlation ID of the audit record"),
fieldWithPath("auditData").description("The data of the audit record"),
fieldWithPath("createdOn").description("The creation date of the audit record"),
Expand Down
73 changes: 33 additions & 40 deletions .../springframework/cloud/dataflow/server/rest/documentation/JobExecutionsDocumentation.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -111,13 +111,12 @@ void listJobExecutions() throws Exception {
get("/jobs/executions")
.queryParam("page", "0")
.queryParam("size", "10"))
.andDo(print())
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
queryParameters(
parameterWithName("page")
.description("The zero-based page number (optional)"),
parameterWithName("size")
.description("The requested page size (optional)")),
parameterWithName("page").optional()
.description("The zero-based page number"),
parameterWithName("size").optional()
.description("The requested page size")),
responseFields(
subsectionWithPath("_embedded.jobExecutionResourceList")
.description("Contains a collection of Job Executions/"),
Expand All @@ -132,13 +131,12 @@ void listThinJobExecutions() throws Exception {
get("/jobs/thinexecutions")
.queryParam("page", "0")
.queryParam("size", "10"))
.andDo(print())
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
queryParameters(
parameterWithName("page")
.description("The zero-based page number (optional)"),
parameterWithName("size")
.description("The requested page size (optional)")),
parameterWithName("page").optional()
.description("The zero-based page number"),
parameterWithName("size").optional()
.description("The requested page size")),
responseFields(
subsectionWithPath("_embedded.jobExecutionThinResourceList")
.description("Contains a collection of Job Executions without step executions included/"),
Expand All @@ -154,13 +152,12 @@ void listThinJobExecutionsByJobInstanceId() throws Exception {
.queryParam("page", "0")
.queryParam("size", "10")
.queryParam("jobInstanceId", "1"))
.andDo(print())
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
queryParameters(
parameterWithName("page")
.description("The zero-based page number (optional)"),
parameterWithName("size")
.description("The requested page size (optional)"),
parameterWithName("page").optional()
.description("The zero-based page number"),
parameterWithName("size").optional()
.description("The requested page size"),
parameterWithName("jobInstanceId")
.description("Filter result by the job instance id")),
responseFields(
Expand All @@ -178,13 +175,12 @@ void listThinJobExecutionsByTaskExecutionId() throws Exception {
.queryParam("page", "0")
.queryParam("size", "10")
.queryParam("taskExecutionId", "1"))
.andDo(print())
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
queryParameters(
parameterWithName("page")
.description("The zero-based page number (optional)"),
parameterWithName("size")
.description("The requested page size (optional)"),
parameterWithName("page").optional()
.description("The zero-based page number"),
parameterWithName("size").optional()
.description("The requested page size"),
parameterWithName("taskExecutionId")
.description("Filter result by the task execution id")),
responseFields(
Expand All @@ -203,13 +199,12 @@ void listThinJobExecutionsByDate() throws Exception {
.queryParam("size", "10")
.queryParam("fromDate", "2000-09-24T17:00:45,000")
.queryParam("toDate", "2050-09-24T18:00:45,000"))
.andDo(print())
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
queryParameters(
parameterWithName("page")
.description("The zero-based page number (optional)"),
parameterWithName("size")
.description("The requested page size (optional)"),
parameterWithName("page").optional()
.description("The zero-based page number"),
parameterWithName("size").optional()
.description("The requested page size"),
parameterWithName("fromDate")
.description("Filter result from a starting date in the format 'yyyy-MM-dd'T'HH:mm:ss,SSS'"),
parameterWithName("toDate")
Expand All @@ -229,13 +224,12 @@ void listJobExecutionsByName() throws Exception {
.queryParam("name", JOB_NAME)
.queryParam("page", "0")
.queryParam("size", "10"))
.andDo(print())
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
queryParameters(
parameterWithName("page")
.description("The zero-based page number (optional)"),
parameterWithName("size")
.description("The requested page size (optional)"),
parameterWithName("page").optional()
.description("The zero-based page number"),
parameterWithName("size").optional()
.description("The requested page size"),
parameterWithName("name")
.description("The name associated with the job execution")),
responseFields(
Expand All @@ -253,13 +247,12 @@ void listThinJobExecutionsByName() throws Exception {
.queryParam("name", JOB_NAME)
.queryParam("page", "0")
.queryParam("size", "10"))
.andDo(print())
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
queryParameters(
parameterWithName("page")
.description("The zero-based page number (optional)"),
parameterWithName("size")
.description("The requested page size (optional)"),
parameterWithName("page").optional()
.description("The zero-based page number"),
parameterWithName("size").optional()
.description("The requested page size"),
parameterWithName("name")
.description("The name associated with the job execution")),
responseFields(
Expand All @@ -278,7 +271,7 @@ void jobDisplayDetail() throws Exception {
.andExpect(status().isOk())
.andDo(this.documentationHandler.document(
pathParameters(
parameterWithName("id").description("The id of an existing job execution (required)")
parameterWithName("id").description("The id of an existing job execution")
),
responseFields(
fieldWithPath("executionId").description("The execution ID of the job execution"),
Expand Down Expand Up @@ -313,9 +306,9 @@ void jobStop() throws Exception {
.andExpect(status().isOk())
.andDo(this.documentationHandler.document(
pathParameters(parameterWithName("id")
.description("The id of an existing job execution (required)"))
.description("The id of an existing job execution"))
, queryParameters(
parameterWithName("stop")
parameterWithName("stop").optional()
.description("Sends signal to stop the job if set to true"))));
}

Expand All @@ -328,12 +321,12 @@ void jobRestart() throws Exception {
.andExpect(status().isOk())
.andDo(this.documentationHandler.document(
pathParameters(parameterWithName("id")
.description("The id of an existing job execution (required)"))
.description("The id of an existing job execution"))
, queryParameters(
parameterWithName("useJsonJobParameters").description("If true dataflow will " +
"serialize job parameters as JSON. Default is null, and the default " +
"configuration will be used to determine serialization method.").optional(),
parameterWithName("restart")
parameterWithName("restart").optional()
.description("Sends signal to restart the job if set to true")
)
)
Expand Down
11 changes: 5 additions & 6 deletions ...g/springframework/cloud/dataflow/server/rest/documentation/JobInstancesDocumentation.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -81,10 +81,10 @@ void listJobInstances() throws Exception {
.param("size", "10"))
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
queryParameters(
parameterWithName("page")
.description("The zero-based page number (optional)"),
parameterWithName("size")
.description("The requested page size (optional)"),
parameterWithName("page").optional()
.description("The zero-based page number"),
parameterWithName("size").optional()
.description("The requested page size"),
parameterWithName("name")
.description("The name associated with the job instance")),
responseFields(
Expand All @@ -98,11 +98,10 @@ void listJobInstances() throws Exception {
void jobDisplayDetail() throws Exception {
this.mockMvc.perform(
get("/jobs/instances/{id}", "1"))
.andDo(print())
.andExpect(status().isOk())
.andDo(this.documentationHandler.document(
pathParameters(
parameterWithName("id").description("The id of an existing job instance (required)")
parameterWithName("id").description("The id of an existing job instance")
),
responseFields(
fieldWithPath("jobName").description("The name of the job instance"),
Expand Down
18 changes: 9 additions & 9 deletions ...ingframework/cloud/dataflow/server/rest/documentation/JobStepExecutionsDocumentation.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -90,12 +90,12 @@ void listStepExecutionsForJob() throws Exception {
.param("size", "10"))
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
queryParameters(
parameterWithName("page")
.description("The zero-based page number (optional)"),
parameterWithName("size")
.description("The requested page size (optional)")),
parameterWithName("page").optional()
.description("The zero-based page number"),
parameterWithName("size").optional()
.description("The requested page size")),
pathParameters(parameterWithName("id")
.description("The id of an existing job execution (required)")),
.description("The id of an existing job execution")),
responseFields(
subsectionWithPath("_embedded.stepExecutionResourceList")
.description("Contains a collection of Step Executions/"),
Expand All @@ -109,9 +109,9 @@ void stepDetail() throws Exception {
get("/jobs/executions/{id}/steps/{stepid}", "1", "1"))
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
pathParameters(
parameterWithName("id").description("The id of an existing job execution (required)"),
parameterWithName("id").description("The id of an existing job execution"),
parameterWithName("stepid")
.description("The id of an existing step execution for a specific job execution (required)")
.description("The id of an existing step execution for a specific job execution")
),
responseFields(
fieldWithPath("jobExecutionId").description("The ID of the job step execution"),
Expand All @@ -129,9 +129,9 @@ void stepProgress() throws Exception {
get("/jobs/executions/{id}/steps/{stepid}/progress", "1", "1"))
.andExpect(status().isOk()).andDo(this.documentationHandler.document(
pathParameters(
parameterWithName("id").description("The id of an existing job execution (required)"),
parameterWithName("id").description("The id of an existing job execution"),
parameterWithName("stepid")
.description("The id of an existing step execution for a specific job execution (required)")
.description("The id of an existing step execution for a specific job execution")
),
responseFields(
subsectionWithPath("stepExecution").description("The detailed step details of the job step execution"),
Expand Down
Loading

0 comments on commit d2a77ef

Please sign in to comment.