From f9383901125362992b663303bf31a4497b0d22dc Mon Sep 17 00:00:00 2001 From: Corneil du Plessis Date: Mon, 28 Oct 2024 12:18:02 +0200 Subject: [PATCH] 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 --- spring-cloud-skipper/pom.xml | 11 ---- .../spring-cloud-skipper-docs/pom.xml | 5 ++ .../src/main/asciidoc/api-guide.adoc | 59 ++++++++++++++++++- .../controller/docs/BaseDocumentation.java | 41 ++++++++++++- .../controller/docs/DeleteDocumentation.java | 8 ++- .../controller/docs/HistoryDocumentation.java | 4 +- .../controller/docs/InstallDocumentation.java | 4 +- .../controller/docs/ListDocumentation.java | 4 +- .../controller/docs/LogsDocumentation.java | 8 ++- .../docs/ManifestDocumentation.java | 8 ++- .../docs/PackageMetadataDocumentation.java | 4 +- .../docs/RepositoriesDocumentation.java | 6 +- .../docs/RollbackDocumentation.java | 9 ++- .../controller/docs/StatusDocumentation.java | 16 +++-- .../asciidoctor/path-parameters.snippet | 11 ++++ .../asciidoctor/query-parameters.snippet | 9 +++ 16 files changed, 176 insertions(+), 31 deletions(-) create mode 100644 spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/resources/org/springframework/restdocs/templates/asciidoctor/path-parameters.snippet create mode 100644 spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/resources/org/springframework/restdocs/templates/asciidoctor/query-parameters.snippet diff --git a/spring-cloud-skipper/pom.xml b/spring-cloud-skipper/pom.xml index 8e2ba03816..45ef4da34f 100644 --- a/spring-cloud-skipper/pom.xml +++ b/spring-cloud-skipper/pom.xml @@ -28,7 +28,6 @@ 3.0.0-SNAPSHOT 1.17 - 3.0.1 0.10.2 3.15.8 @@ -181,16 +180,6 @@ java-semver ${java-semver.version} - - org.springframework.restdocs - spring-restdocs-mockmvc - ${spring-restdocs.version} - - - org.springframework.restdocs - spring-restdocs-core - ${spring-restdocs.version} - nl.jqno.equalsverifier equalsverifier diff --git a/spring-cloud-skipper/spring-cloud-skipper-docs/pom.xml b/spring-cloud-skipper/spring-cloud-skipper-docs/pom.xml index 431d158fa7..638f2ea5d7 100644 --- a/spring-cloud-skipper/spring-cloud-skipper-docs/pom.xml +++ b/spring-cloud-skipper/spring-cloud-skipper-docs/pom.xml @@ -45,6 +45,11 @@ spring-boot-starter-test test + + org.springframework.restdocs + spring-restdocs-mockmvc + test + org.springframework.restdocs spring-restdocs-core diff --git a/spring-cloud-skipper/spring-cloud-skipper-docs/src/main/asciidoc/api-guide.adoc b/spring-cloud-skipper/spring-cloud-skipper-docs/src/main/asciidoc/api-guide.adoc index 9ea2fc88e4..0d404f4554 100644 --- a/spring-cloud-skipper/spring-cloud-skipper-docs/src/main/asciidoc/api-guide.adoc +++ b/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[] diff --git a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/BaseDocumentation.java b/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/BaseDocumentation.java index af357adfe4..5925473e66 100644 --- a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/BaseDocumentation.java +++ b/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; + } + } + } } diff --git a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/DeleteDocumentation.java b/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/DeleteDocumentation.java index 60a57ec151..9db043e7cb 100644 --- a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/DeleteDocumentation.java +++ b/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"), diff --git a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/HistoryDocumentation.java b/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/HistoryDocumentation.java index 1d8f747bb6..d5a94245e3 100644 --- a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/HistoryDocumentation.java +++ b/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(), diff --git a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/InstallDocumentation.java b/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/InstallDocumentation.java index cacb529f19..63131f5b72 100644 --- a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/InstallDocumentation.java +++ b/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"), diff --git a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/ListDocumentation.java b/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/ListDocumentation.java index 904adb3de0..3db3a0e78e 100644 --- a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/ListDocumentation.java +++ b/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"), diff --git a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/LogsDocumentation.java b/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/LogsDocumentation.java index 2f21003776..9f3f0d524c 100644 --- a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/LogsDocumentation.java +++ b/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())); } } diff --git a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/ManifestDocumentation.java b/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/ManifestDocumentation.java index 6b2ae5d123..d04ace293e 100644 --- a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/ManifestDocumentation.java +++ b/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/ManifestDocumentation.java @@ -26,8 +26,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 Gunnar Hillert * @author Ilayaperumal Gopinathan @@ -47,6 +48,7 @@ void getManifestOfRelease() throws Exception { .contentType(contentType)) .andExpect(status().isOk()) .andDo(this.documentationHandler.document( + pathParameters(parameterWithName("releaseName").description("The name of the release")), responseBody())); } @@ -61,6 +63,10 @@ void getManifestOfReleaseForVersion() throws Exception { release.getName(), release.getVersion())) .andExpect(status().isOk()) .andDo(this.documentationHandler.document( + pathParameters( + parameterWithName("releaseName").description("The name of the release"), + parameterWithName("releaseVersion").description("The version of the release") + ), responseBody())); } } diff --git a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/PackageMetadataDocumentation.java b/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/PackageMetadataDocumentation.java index bd283b1cab..c7db183943 100644 --- a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/PackageMetadataDocumentation.java +++ b/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/PackageMetadataDocumentation.java @@ -153,7 +153,7 @@ void getPackageMetadataSearchFindByName() throws Exception { packageMetadata.setRepositoryId(this.repositoryRepository.findByName("local").getId()); PackageMetadata saved = this.packageMetadataRepository.save(pkg.getMetadata()); this.mockMvc.perform( - get("/api/packageMetadata/search/findByName?name=log")) + get("/api/packageMetadata/search/findByName").queryParam("name", "log")) .andExpect(status().isOk()) .andDo(this.documentationHandler.document( queryParameters(parameterWithName("name").description("The name of the Package")), @@ -197,7 +197,7 @@ void getPackageMetadataSearchFindByNameContainingIgnoreCase() throws Exception { packageMetadata.setRepositoryId(this.repositoryRepository.findByName("local").getId()); PackageMetadata saved = this.packageMetadataRepository.save(pkg.getMetadata()); this.mockMvc.perform( - get("/api/packageMetadata/search/findByNameContainingIgnoreCase?name=LO")) + get("/api/packageMetadata/search/findByNameContainingIgnoreCase").queryParam("name","LO")) .andExpect(status().isOk()) .andDo(this.documentationHandler.document( queryParameters(parameterWithName("name").description("The name of the Package")), diff --git a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/RepositoriesDocumentation.java b/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/RepositoriesDocumentation.java index e4a7d1e19d..05a0ee895e 100644 --- a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/RepositoriesDocumentation.java +++ b/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/RepositoriesDocumentation.java @@ -23,8 +23,9 @@ import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get; import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath; import static org.springframework.restdocs.payload.PayloadDocumentation.responseFields; +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 Corneil du Plessis @@ -62,9 +63,10 @@ void getAllRepositories() throws Exception { void getSingleRepository() throws Exception { this.mockMvc.perform( - get("/api/repositories/search/findByName?name={name}", "local")) + get("/api/repositories/search/findByName").queryParam("name", "local")) .andExpect(status().isOk()) .andDo(this.documentationHandler.document( + queryParameters(parameterWithName("name").description("Name of the Repository")), responseFields( fieldWithPath("name").description("Name of the Repository"), fieldWithPath("url").description("URL of the Repository"), diff --git a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/RollbackDocumentation.java b/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/RollbackDocumentation.java index 4a8ee7c0b0..639f30eb60 100644 --- a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/RollbackDocumentation.java +++ b/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/RollbackDocumentation.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 @@ -47,9 +48,11 @@ void rollbackRelease() throws Exception { Release release = createTestRelease(); when(this.skipperStateMachineService.rollbackRelease(any(RollbackRequest.class))).thenReturn(release); MvcResult result = this.mockMvc.perform( - post("/api/release/rollback/{releaseName}/{releaseVersion}", - release.getName(), release.getVersion())).andExpect(status().isCreated()) + post("/api/release/rollback/{releaseName}/{releaseVersion}", release.getName(), release.getVersion()) + ).andExpect(status().isCreated()) .andDo(this.documentationHandler.document( + pathParameters(parameterWithName("releaseName").description("The name of the release to rollback"), + parameterWithName("releaseVersion").description("The release version to rollback")), responseFields( subsectionWithPath("_links").ignored(), fieldWithPath("name").description("Name of the release"), diff --git a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/StatusDocumentation.java b/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/StatusDocumentation.java index 5429a446fd..775152d34d 100644 --- a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/StatusDocumentation.java +++ b/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/java/org/springframework/cloud/skipper/server/controller/docs/StatusDocumentation.java @@ -27,8 +27,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 @@ -41,8 +42,11 @@ void getStatusOfRelease() throws Exception { Release release = createTestRelease(); when(this.releaseService.status(release.getName())).thenReturn(release.getInfo()); this.mockMvc.perform( - get("/api/release/status/{releaseName}", release.getName())).andExpect(status().isOk()) + get("/api/release/status/{releaseName}", release.getName()) + ) + .andExpect(status().isOk()) .andDo(this.documentationHandler.document( + pathParameters(parameterWithName("releaseName").description("The name of the release")), responseFields( subsectionWithPath("_links").ignored(), fieldWithPath("status.statusCode").description( @@ -62,10 +66,14 @@ void getStatusOfReleaseForVersion() throws Exception { Release release = createTestRelease(); when(this.releaseService.status(release.getName(), release.getVersion())).thenReturn(release.getInfo()); this.mockMvc.perform( - get("/api/release/status/{releaseName}/{releaseVersion}", - release.getName(), release.getVersion())) + get("/api/release/status/{releaseName}/{releaseVersion}", release.getName(), release.getVersion()) + ) .andExpect(status().isOk()) .andDo(this.documentationHandler.document( + pathParameters( + parameterWithName("releaseName").description("The name of the release"), + parameterWithName("releaseVersion").description("The version of the release") + ), responseFields( subsectionWithPath("_links").ignored(), fieldWithPath("status.statusCode").description( diff --git a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/resources/org/springframework/restdocs/templates/asciidoctor/path-parameters.snippet b/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/resources/org/springframework/restdocs/templates/asciidoctor/path-parameters.snippet new file mode 100644 index 0000000000..dfd62e5661 --- /dev/null +++ b/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/resources/org/springframework/restdocs/templates/asciidoctor/path-parameters.snippet @@ -0,0 +1,11 @@ +`*{{path}}*` +|=== +|Parameter - Description + +{{#parameters}} +|{{#tableCellContent}}`*{{name}}*` {{#optional}} [small]#_(optional)_#{{/optional}}{{^optional}} [small]#*(required)*#{{/optional}}{{/tableCellContent}} + +{{#tableCellContent}}{{description}}{{/tableCellContent}} + +{{/parameters}} +|=== \ No newline at end of file diff --git a/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/resources/org/springframework/restdocs/templates/asciidoctor/query-parameters.snippet b/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/resources/org/springframework/restdocs/templates/asciidoctor/query-parameters.snippet new file mode 100644 index 0000000000..a0712f5952 --- /dev/null +++ b/spring-cloud-skipper/spring-cloud-skipper-server-core/src/test/resources/org/springframework/restdocs/templates/asciidoctor/query-parameters.snippet @@ -0,0 +1,9 @@ +|=== +|Parameter - Description +{{#parameters}} +|{{#tableCellContent}}`*{{name}}*` {{#optional}} [small]#_(optional)_#{{/optional}}{{^optional}} [small]#*(required)*#{{/optional}}{{/tableCellContent}} + +{{#tableCellContent}}{{description}}{{/tableCellContent}} + +{{/parameters}} +|=== \ No newline at end of file