Fix rest documentation for changes to spring-rest-docs in skipper (#6024)

Added query-parameters and path-parameters where applicable.

Added snippet template to query-parameters and updated template for path-parameters to improve readability.

Fixes #6008

Author: Corneil du Plessis

spring-cloud-skipper/pom.xml

@@ -28,7 +28,6 @@
 		<spring-cloud-deployer.version>3.0.0-SNAPSHOT</spring-cloud-deployer.version>
 
 		<zeroturnaround.version>1.17</zeroturnaround.version>
-		<spring-restdocs.version>3.0.1</spring-restdocs.version>
 		<java-semver.version>0.10.2</java-semver.version>
 
 		<equalverifier.version>3.15.8</equalverifier.version>
@@ -181,16 +180,6 @@
 				<artifactId>java-semver</artifactId>
 				<version>${java-semver.version}</version>
 			</dependency>
-			<dependency>
-				<groupId>org.springframework.restdocs</groupId>
-				<artifactId>spring-restdocs-mockmvc</artifactId>
-				<version>${spring-restdocs.version}</version>
-			</dependency>
-			<dependency>
-				<groupId>org.springframework.restdocs</groupId>
-				<artifactId>spring-restdocs-core</artifactId>
-				<version>${spring-restdocs.version}</version>
-			</dependency>
 			<dependency>
 				<groupId>nl.jqno.equalsverifier</groupId>
 				<artifactId>equalsverifier</artifactId>

spring-cloud-skipper/spring-cloud-skipper-docs/pom.xml

@@ -45,6 +45,11 @@
 			<artifactId>spring-boot-starter-test</artifactId>
 			<scope>test</scope>
 		</dependency>
+		<dependency>
+			<groupId>org.springframework.restdocs</groupId>
+			<artifactId>spring-restdocs-mockmvc</artifactId>
+			<scope>test</scope>
+		</dependency>
 		<dependency>
 			<groupId>org.springframework.restdocs</groupId>
 			<artifactId>spring-restdocs-core</artifactId>

spring-cloud-skipper/spring-cloud-skipper-docs/src/main/asciidoc/api-guide.adoc

@@ -158,6 +158,10 @@ A `GET` request returns a paginated list for all the Spring Cloud Skipper platfo
 
 include::{snippets}/deployers-documentation/get-all-deployers/http-request.adoc[]
 
+===== Request parameters
+
+include::{snippets}/deployers-documentation/get-all-deployers/query-parameters.adoc[]
+
 ===== Example request
 
 include::{snippets}/deployers-documentation/get-all-deployers/curl-request.adoc[]
@@ -184,6 +188,10 @@ A `GET` request will return a paginated list for all Spring Cloud Skipper packag
 
 include::{snippets}/package-metadata-documentation/get-all-package-metadata/http-request.adoc[]
 
+===== Path parameters
+
+include::{snippets}/package-metadata-documentation/get-all-package-metadata/query-parameters.adoc[]
+
 ===== Example request
 
 include::{snippets}/package-metadata-documentation/get-all-package-metadata/curl-request.adoc[]
@@ -227,6 +235,11 @@ A `GET` request returns the details of a package using the `id` of the package.
 
 include::{snippets}/package-metadata-documentation/get-package-metadata-details/http-request.adoc[]
 
+===== Path parameters
+
+include::{snippets}/package-metadata-documentation/get-package-metadata-details/path-parameters.adoc[]
+
+
 ===== Example request
 
 include::{snippets}/package-metadata-documentation/get-package-metadata-details/curl-request.adoc[]
@@ -248,6 +261,10 @@ A `GET` request returns a list of all the Spring Cloud Skipper package metadata
 getPackageMetadataSearchFindByName
 include::{snippets}/package-metadata-documentation/get-package-metadata-search-find-by-name/http-request.adoc[]
 
+===== Request parameters
+
+include::{snippets}/package-metadata-documentation/get-package-metadata-search-find-by-name/query-parameters.adoc[]
+
 ===== Example request
 
 include::{snippets}/package-metadata-documentation/get-package-metadata-search-find-by-name/curl-request.adoc[]
@@ -267,7 +284,11 @@ A `GET` request returns a list for all Spring Cloud Skipper package metadata by
 
 ===== Request structure
 
-include::{snippets}/package-metadata-documentation/get-package-metadata-search-find-by-name-containing-ignore-case//http-request.adoc[]
+include::{snippets}/package-metadata-documentation/get-package-metadata-search-find-by-name-containing-ignore-case/http-request.adoc[]
+
+===== Request parameters
+
+include::{snippets}/package-metadata-documentation/get-package-metadata-search-find-by-name-containing-ignore-case/query-parameters.adoc[]
 
 ===== Example request
 
@@ -338,6 +359,10 @@ The `install` link can install a package identified by its ID into the target pl
 
 include::{snippets}/install-documentation/install-package-with-id/http-request.adoc[]
 
+===== Path parameters
+
+include::{snippets}/install-documentation/install-package-with-id/path-parameters.adoc[]
+
 ===== Example request
 
 include::{snippets}/install-documentation/install-package-with-id/curl-request.adoc[]
@@ -458,6 +483,10 @@ given release name.
 
 include::{snippets}/list-documentation/list-releases-by-release-name/http-request.adoc[]
 
+====== Path parameters
+
+include::{snippets}/list-documentation/list-releases-by-release-name/path-parameters.adoc[]
+
 ====== Example request
 
 include::{snippets}/list-documentation/list-releases-by-release-name/curl-request.adoc[]
@@ -481,6 +510,10 @@ The `status` REST endpoint provides the status for the last known release versio
 
 include::{snippets}/status-documentation/get-status-of-release/http-request.adoc[]
 
+====== Path parameters
+
+include::{snippets}/status-documentation/get-status-of-release/path-parameters.adoc[]
+
 ====== Example request
 
 include::{snippets}/status-documentation/get-status-of-release/curl-request.adoc[]
@@ -501,6 +534,10 @@ The `status` REST endpoint can provide the status for a specific release version
 
 include::{snippets}/status-documentation/get-status-of-release-for-version/http-request.adoc[]
 
+====== Path parameters
+
+include::{snippets}/status-documentation/get-status-of-release-for-version/path-parameters.adoc[]
+
 ====== Example request
 
 include::{snippets}/status-documentation/get-status-of-release-for-version/curl-request.adoc[]
@@ -554,6 +591,10 @@ This part of the api is deprecated, please use
 
 include::{snippets}/rollback-documentation/rollback-release/http-request.adoc[]
 
+====== Path parameters
+
+include::{snippets}/rollback-documentation/rollback-release/path-parameters.adoc[]
+
 ====== Example request
 
 include::{snippets}/rollback-documentation/rollback-release/curl-request.adoc[]
@@ -598,6 +639,10 @@ The `manifest` REST endpoint returns the manifest for the last known release ver
 
 include::{snippets}/manifest-documentation/get-manifest-of-release/http-request.adoc[]
 
+====== Path parameters
+
+include::{snippets}/manifest-documentation/get-manifest-of-release/path-parameters.adoc[]
+
 ====== Example request
 
 include::{snippets}/manifest-documentation/get-manifest-of-release/curl-request.adoc[]
@@ -614,6 +659,10 @@ The `manifest` REST endpoint can return the manifest for a specific release vers
 
 include::{snippets}/manifest-documentation/get-manifest-of-release-for-version/http-request.adoc[]
 
+====== Path parameters
+
+include::{snippets}/manifest-documentation/get-manifest-of-release-for-version/path-parameters.adoc[]
+
 ====== Example request
 
 include::{snippets}/manifest-documentation/get-manifest-of-release-for-version/curl-request.adoc[]
@@ -635,6 +684,10 @@ The delete operation does not uninstall the uploaded packages corresponding to t
 
 include::{snippets}/delete-documentation/delete-release-default/http-request.adoc[]
 
+====== Path Parameters
+
+include::{snippets}/delete-documentation/delete-release-default/path-parameters.adoc[]
+
 ====== Example request
 
 include::{snippets}/delete-documentation/delete-release-default/curl-request.adoc[]
@@ -655,6 +708,10 @@ You can use a DELETE request to delete an existing release and uninstall the pac
 
 include::{snippets}/delete-documentation/delete-release/http-request.adoc[]
 
+====== Path Parameters
+
+include::{snippets}/delete-documentation/delete-release-default/path-parameters.adoc[]
+
 ====== Example request
 
 include::{snippets}/delete-documentation/delete-release/curl-request.adoc[]

spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/BaseDocumentation.java

@@ -21,6 +21,7 @@
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.concurrent.Callable;
 
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.databind.ObjectMapper;
@@ -66,6 +67,8 @@
 import org.springframework.restdocs.request.QueryParametersSnippet;
 import org.springframework.test.context.ActiveProfiles;
 import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.test.web.servlet.MvcResult;
+import org.springframework.test.web.servlet.ResultHandler;
 import org.springframework.test.web.servlet.setup.MockMvcBuilders;
 import org.springframework.web.context.WebApplicationContext;
 import org.springframework.web.servlet.config.annotation.EnableWebMvc;
@@ -110,6 +113,7 @@ public abstract class BaseDocumentation {
 	@Autowired
 	public WebApplicationContext context;
 
+	protected RestDocs documentation;
 
 	@Autowired
 	protected RepositoryRepository repositoryRepository;
@@ -186,13 +190,13 @@ private void prepareDocumentationTests(WebApplicationContext context) {
 		this.documentationHandler = document("{class-name}/{method-name}",
 				preprocessRequest(prettyPrint()),
 				preprocessResponse(prettyPrint()));
-
+		this.documentation = new ToggleableResultHandler(documentationHandler);
 		this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
 				.apply(this.restDocumentationConfigurer.uris()
 						.withScheme("http")
 						.withHost("localhost")
 						.withPort(7577))
-				.alwaysDo(this.documentationHandler)
+				.alwaysDo((ToggleableResultHandler) this.documentation)
 				.build();
 	}
 
@@ -269,5 +273,38 @@ protected static String convertObjectToJson(Object object) throws IOException {
 		String json = mapper.writeValueAsString(object);
 		return json;
 	}
+	@FunctionalInterface
+	public interface RestDocs {
+		void dontDocument(Callable action) throws Exception;
+	}
+	private static class ToggleableResultHandler implements ResultHandler, RestDocs {
+		private final ResultHandler delegate;
+
+		private boolean off = false;
+
+		private ToggleableResultHandler(ResultHandler delegate) {
+			this.delegate = delegate;
+		}
+
+		@Override
+		public void handle(MvcResult result) throws Exception {
+			if (!off) {
+				delegate.handle(result);
+			}
+		}
+
+		/**
+		 * Perform the given action while turning off the delegate handler.
+		 */
+		@Override
+		public void dontDocument(Callable action) throws Exception {
+			off = true;
+			try {
+				action.call();
+			} finally {
+				off = false;
+			}
+		}
+	}
 
 }

spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/DeleteDocumentation.java

@@ -32,8 +32,9 @@
 import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
 import static org.springframework.restdocs.payload.PayloadDocumentation.responseFields;
 import static org.springframework.restdocs.payload.PayloadDocumentation.subsectionWithPath;
+import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
+import static org.springframework.restdocs.request.RequestDocumentation.pathParameters;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
-
 /**
  * @author Gunnar Hillert
  * @author Ilayaperumal Gopinathan
@@ -44,12 +45,16 @@ class DeleteDocumentation extends BaseDocumentation {
 	@Test
 	void deleteRelease() throws Exception {
 		Release release = createTestRelease("test", StatusCode.DELETED);
+
 		when(this.skipperStateMachineService.deleteRelease(any(String.class), any(DeleteProperties.class))).thenReturn(release);
 		this.mockMvc.perform(
 				delete("/api/release/{releaseName}/package", release.getName())
 						.accept(MediaType.APPLICATION_JSON).contentType(MediaType.APPLICATION_JSON))
 				.andExpect(status().isOk())
 				.andDo(this.documentationHandler.document(
+						pathParameters(
+								parameterWithName("releaseName").description("The name of the release to be deleted")
+						),
 						responseFields(
 								subsectionWithPath("links").ignored(),
 								fieldWithPath("name").description("Name of the release"),
@@ -117,6 +122,7 @@ void deleteReleaseDefault() throws Exception {
 						.accept(MediaType.APPLICATION_JSON).contentType(contentType))
 				.andExpect(status().isOk())
 				.andDo(this.documentationHandler.document(
+						pathParameters(parameterWithName("releaseName").description("Name of the release to be deleted")),
 						responseFields(
 								subsectionWithPath("links").ignored(),
 								fieldWithPath("name").description("Name of the release"),

spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/HistoryDocumentation.java

@@ -26,8 +26,9 @@
 import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
 import static org.springframework.restdocs.payload.PayloadDocumentation.responseFields;
 import static org.springframework.restdocs.payload.PayloadDocumentation.subsectionWithPath;
+import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
+import static org.springframework.restdocs.request.RequestDocumentation.queryParameters;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
-
 /**
  * @author Gunnar Hillert
  * @author Ilayaperumal Gopinathan
@@ -43,6 +44,7 @@ void showVersionHistoryForRelease() throws Exception {
 		this.mockMvc.perform(
 				get("/api/releases/search/findByNameIgnoreCaseContainingOrderByNameAscVersionDesc?name={name}", "test")).andExpect(status().isOk())
 				.andDo(this.documentationHandler.document(
+						queryParameters(parameterWithName("name").description("Name of release")),
 						responseFields(
 								subsectionWithPath("_links").ignored(),
 								subsectionWithPath("_embedded.releases[]._links").ignored(),

spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/InstallDocumentation.java

@@ -33,8 +33,9 @@
 import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
 import static org.springframework.restdocs.payload.PayloadDocumentation.responseFields;
 import static org.springframework.restdocs.payload.PayloadDocumentation.subsectionWithPath;
+import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
+import static org.springframework.restdocs.request.RequestDocumentation.pathParameters;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
-
 /**
  * @author Gunnar Hillert
  * @author Ilayaperumal Gopinathan
@@ -143,6 +144,7 @@ void installPackageWithId() throws Exception {
 				.contentType(contentType)
 				.content(convertObjectToJson(installProperties2))).andExpect(status().isCreated())
 				.andDo(this.documentationHandler.document(
+						pathParameters(parameterWithName("packageMetaDataId").description("Id of package to install")),
 						responseFields(
 								subsectionWithPath("links").ignored(),
 								fieldWithPath("name").description("Name of the release"),

spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/ListDocumentation.java

@@ -30,8 +30,9 @@
 import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
 import static org.springframework.restdocs.payload.PayloadDocumentation.responseFields;
 import static org.springframework.restdocs.payload.PayloadDocumentation.subsectionWithPath;
+import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
+import static org.springframework.restdocs.request.RequestDocumentation.pathParameters;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
-
 /**
  * @author Gunnar Hillert
  * @author Ilayaperumal Gopinathan
@@ -115,6 +116,7 @@ void listReleasesByReleaseName() throws Exception {
 		this.mockMvc.perform(
 				get("/api/release/list/{releaseName}", release.getName())).andExpect(status().isOk())
 				.andDo(this.documentationHandler.document(
+						pathParameters(parameterWithName("releaseName").description("Name of the releases to list")),
 						responseFields(
 								subsectionWithPath("_embedded.releases[]._links").ignored(),
 								fieldWithPath("_embedded.releases[].name").description("Name of the release"),

spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/LogsDocumentation.java

@@ -28,8 +28,9 @@
 import static org.mockito.Mockito.when;
 import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
 import static org.springframework.restdocs.payload.PayloadDocumentation.responseBody;
+import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
+import static org.springframework.restdocs.request.RequestDocumentation.pathParameters;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
-
 /**
  * @author Ilayaperumal Gopinathan
  * @author Corneil du Plessis
@@ -48,6 +49,7 @@ void getLogsofRelease() throws Exception {
 						.contentType(contentType))
 				.andExpect(status().isOk())
 				.andDo(this.documentationHandler.document(
+						pathParameters(parameterWithName("releaseName").description("The name of the release to show logs")),
 						responseBody()));
 	}
 
@@ -61,6 +63,10 @@ void getLogsofReleaseByAppName() throws Exception {
 						release.getName(), "myapp"))
 				.andExpect(status().isOk())
 				.andDo(this.documentationHandler.document(
+						pathParameters(
+							parameterWithName("releaseName").description("The name of the release to show logs"),
+							parameterWithName("appName").description("The name of the app to show logs")
+						),
 						responseBody()));
 	}
 }