From 0b55e4f60d70936c16cd6e5c2d178b6f997bf05b Mon Sep 17 00:00:00 2001 From: Volker Schmidt Date: Tue, 13 Nov 2018 21:29:18 +0100 Subject: [PATCH] Added more documentation for REST interfaces. --- fhir/pom.xml | 1 + fhir/src/main/asciidoc/api-guide.adoc | 8 +++ .../CodeRepositoryRestDocsTest.java | 59 ++++++++++++++++++- pom.xml | 2 + 4 files changed, 69 insertions(+), 1 deletion(-) diff --git a/fhir/pom.xml b/fhir/pom.xml index 2147fb38..47449509 100644 --- a/fhir/pom.xml +++ b/fhir/pom.xml @@ -122,6 +122,7 @@ process-asciidoc + ${skipTests} html book diff --git a/fhir/src/main/asciidoc/api-guide.adoc b/fhir/src/main/asciidoc/api-guide.adoc index e3da2b6f..76cb5cc3 100644 --- a/fhir/src/main/asciidoc/api-guide.adoc +++ b/fhir/src/main/asciidoc/api-guide.adoc @@ -151,7 +151,15 @@ Resources can be divided into three groups: The response body resource examples in this document use by default content type application/hal+json. +Sorting and paging can be achieved as seen below. +.Read resource sorted and paged curl snippet +include::{snippets}/read-codes-sorted-paged/curl-request.adoc[] + +.Read resource sorted and paged response body +include::{snippets}/read-codes-sorted-paged/response-body.adoc[] + +include::{snippets}/read-codes-sorted-paged/response-fields.adoc[] [[api-resources-code]] === Code Mapping Resources diff --git a/fhir/src/test/java/org/dhis2/fhir/adapter/fhir/metadata/repository/CodeRepositoryRestDocsTest.java b/fhir/src/test/java/org/dhis2/fhir/adapter/fhir/metadata/repository/CodeRepositoryRestDocsTest.java index 01fb4374..285b5b27 100644 --- a/fhir/src/test/java/org/dhis2/fhir/adapter/fhir/metadata/repository/CodeRepositoryRestDocsTest.java +++ b/fhir/src/test/java/org/dhis2/fhir/adapter/fhir/metadata/repository/CodeRepositoryRestDocsTest.java @@ -49,6 +49,8 @@ import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get; import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.post; import static org.springframework.restdocs.payload.PayloadDocumentation.*; +import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName; +import static org.springframework.restdocs.request.RequestDocumentation.requestParameters; import static org.springframework.restdocs.snippet.Attributes.attributes; import static org.springframework.restdocs.snippet.Attributes.key; import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*; @@ -109,7 +111,7 @@ public void readCode() throws Exception linkWithRel( "self" ).description( "Link to this resource itself." ), linkWithRel( "code" ).description( "Link to this resource itself." ), linkWithRel( "codeCategory" ).description( "Link to this resource itself." ) ), responseFields( - attributes( key( "title" ).value( "Fields for code category reading" ) ), + attributes( key( "title" ).value( "Fields for code reading" ) ), fields.withPath( "createdAt" ).description( "The timestamp when the resource has been created." ).type( JsonFieldType.STRING ), fields.withPath( "lastUpdatedBy" ).description( "The ID of the user that has updated the user the last time or null if the data has been imported to the database directly." ).type( JsonFieldType.STRING ).optional(), fields.withPath( "lastUpdatedAt" ).description( "The timestamp when the resource has been updated the last time." ).type( JsonFieldType.STRING ), @@ -121,6 +123,61 @@ public void readCode() throws Exception ) ) ); } + @Test + public void readCodesPaged() throws Exception + { + final ConstrainedFields fields = new ConstrainedFields( Code.class, constraintDescriptionResolver ); + docMockMvc.perform( get( "/api/codes" ).param( "size", "3" ).header( AUTHORIZATION_HEADER_NAME, CODE_MAPPING_AUTHORIZATION_HEADER_VALUE ) ) + .andExpect( status().isOk() ) + .andDo( documentationHandler.document( links( + linkWithRel( "self" ).description( "Link to this resource itself." ), + linkWithRel( "first" ).description( "Link to the first page of the paged resource." ), + linkWithRel( "prev" ).description( "Link to the previous page (if any) of the paged resource." ).optional(), + linkWithRel( "next" ).description( "Link to the next page (if any) of the paged resource." ).optional(), + linkWithRel( "last" ).description( "Link to the last page of the paged resource." ), + linkWithRel( "profile" ).description( "Link to the profile of this resource." ) ), responseFields( + attributes( key( "title" ).value( "Fields for paged code reading" ) ), + fieldWithPath( "page" ).description( "The paging information." ).type( JsonFieldType.OBJECT ), + fieldWithPath( "page.size" ).description( "The used page size (may be less than the specified amount)." ).type( JsonFieldType.NUMBER ), + fieldWithPath( "page.totalElements" ).description( "The total amount of elements." ).type( JsonFieldType.NUMBER ), + fieldWithPath( "page.totalPages" ).description( "The total number of pages." ).type( JsonFieldType.NUMBER ), + fieldWithPath( "page.number" ).description( "The current page number." ).type( JsonFieldType.NUMBER ), + subsectionWithPath( "_embedded" ).ignored(), + subsectionWithPath( "_links" ).description( "Links to other resources" ) + ) + ) ); + } + + @Test + public void readCodesSortedPaged() throws Exception + { + final ConstrainedFields fields = new ConstrainedFields( Code.class, constraintDescriptionResolver ); + docMockMvc.perform( get( "/api/codes" ).param( "page", "0" ).param( "size", "3" ).param( "sort", "lastUpdatedAt,desc" ) + .header( AUTHORIZATION_HEADER_NAME, CODE_MAPPING_AUTHORIZATION_HEADER_VALUE ) ) + .andExpect( status().isOk() ) + .andDo( documentationHandler.document( links( + linkWithRel( "self" ).description( "Link to this resource itself." ), + linkWithRel( "first" ).description( "Link to the first page of the paged resource." ), + linkWithRel( "prev" ).description( "Link to the previous page (if any) of the paged resource." ).optional(), + linkWithRel( "next" ).description( "Link to the next page (if any) of the paged resource." ).optional(), + linkWithRel( "last" ).description( "Link to the last page of the paged resource." ), + linkWithRel( "profile" ).description( "Link to the profile of this resource." ) ), requestParameters( + parameterWithName( "page" ).description( "The current page number to display." ).optional(), + parameterWithName( "size" ).description( "The number of elements to display one one page." ).optional(), + parameterWithName( "sort" ).description( "The sort that should be applied with format propertyName[,asc|desc]" ).optional() + ), responseFields( + attributes( key( "title" ).value( "Fields for paged code reading" ) ), + fieldWithPath( "page" ).description( "The paging information." ).type( JsonFieldType.OBJECT ), + fieldWithPath( "page.size" ).description( "The used page size (may be less than the specified amount)." ).type( JsonFieldType.NUMBER ), + fieldWithPath( "page.totalElements" ).description( "The total amount of elements." ).type( JsonFieldType.NUMBER ), + fieldWithPath( "page.totalPages" ).description( "The total number of pages." ).type( JsonFieldType.NUMBER ), + fieldWithPath( "page.number" ).description( "The current page number." ).type( JsonFieldType.NUMBER ), + subsectionWithPath( "_embedded" ).ignored(), + subsectionWithPath( "_links" ).description( "Links to other resources" ) + ) + ) ); + } + @Nonnull protected Code loadCode( @Nonnull String code ) { diff --git a/pom.xml b/pom.xml index 3c5194a2..18acf4a4 100644 --- a/pom.xml +++ b/pom.xml @@ -65,6 +65,8 @@ 3.6.0 2.0.1.RELEASE + + false