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

Fix rest documentation for changes to spring-rest-docs #6012

Merged
merged 3 commits into from
Oct 28, 2024
Merged

Fix rest documentation for changes to spring-rest-docs #6012

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
faf25c1
Fix rest documentation for changes to spring-rest-docs
Oct 24, 2024
ef59179
Update from review
Oct 25, 2024
d5822b1
Merge branch 'main' into corneil/fix-rest-docs-query-parameters
Oct 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 13 additions & 11 deletions ...rg/springframework/cloud/dataflow/server/rest/documentation/AppRegistryDocumentation.java
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Loading