iSharkFly-Docs
/
java-tutorials
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #3370 from eugenp/update-rest-docs 

update restdocs, move to spring-5
This commit is contained in:
Loredana Crusoveanu 2018-01-09 22:55:36 +02:00 committed by GitHub
parent 92e8b0b8b0 fa2e225d63
commit c977b6feaa
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
15 changed files with 514 additions and 537 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
pom.xml
View File

@ -203,7 +203,6 @@
<module>spring-protobuf</module>
<module>spring-quartz</module>
<module>spring-rest-angular</module>
<module>spring-rest-docs</module>
<module>spring-rest-full</module>
<module>spring-rest-query-language</module>
<module>spring-rest</module>

46
spring-5/pom.xml
View File

@ -39,6 +39,10 @@
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webflux</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-hateoas</artifactId>
</dependency>
<dependency>
<groupId>org.projectreactor</groupId>
<artifactId>reactor-spring</artifactId>
@ -135,6 +139,23 @@
<version>${junit.platform.version}</version>
<scope>test</scope>
</dependency>
<!-- restdocs -->
<dependency>
<groupId>org.springframework.restdocs</groupId>
<artifactId>spring-restdocs-mockmvc</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.springframework.restdocs</groupId>
<artifactId>spring-restdocs-webtestclient</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.springframework.restdocs</groupId>
<artifactId>spring-restdocs-restassured</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
@ -163,6 +184,29 @@
</excludes>
</configuration>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>${asciidoctor-plugin.version}</version>
<executions>
<execution>
<id>generate-docs</id>
<phase>package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html</backend>
<doctype>book</doctype>
<attributes>
<snippets>${snippetsDirectory}</snippets>
</attributes>
<sourceDirectory>src/docs/asciidocs</sourceDirectory>
<outputDirectory>target/generated-docs</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
@ -199,6 +243,8 @@
<johnzon.version>1.1.3</johnzon.version>
<jsonb-api.version>1.0</jsonb-api.version>
<geronimo-json_1.1_spec.version>1.0</geronimo-json_1.1_spec.version>
<asciidoctor-plugin.version>1.5.6</asciidoctor-plugin.version>
<snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
</properties>
</project>

48
spring-rest-docs/src/docs/asciidocs/api-guide.adoc → spring-5/src/docs/asciidocs/api-guide.adoc
View File

@ -55,13 +55,6 @@ use of HTTP status codes.
| The requested resource did not exist
|===
[[overview-headers]]
== Headers
Every response has the following header(s):
include::{snippets}/headers-example/response-headers.adoc[]
[[overview-hypermedia]]
== Hypermedia
@ -86,18 +79,14 @@ The index provides the entry point into the service.
A `GET` request is used to access the index
==== Response structure
==== Request structure
include::{snippets}/index-example/http-response.adoc[]
include::{snippets}/index-example/http-request.adoc[]
==== Example response
include::{snippets}/index-example/http-response.adoc[]
==== Example request
include::{snippets}/index-example/http-request.adoc[]
==== CURL request
include::{snippets}/index-example/curl-request.adoc[]
@ -113,12 +102,12 @@ include::{snippets}/index-example/links.adoc[]
The CRUD provides the entry point into the service.
[[resources-crud-access]]
[[resources-crud-get]]
=== Accessing the crud GET
A `GET` request is used to access the CRUD read
A `GET` request is used to access the CRUD read.
==== Response structure
==== Request structure
include::{snippets}/crud-get-example/http-request.adoc[]
@ -130,12 +119,12 @@ include::{snippets}/crud-get-example/http-response.adoc[]
include::{snippets}/crud-get-example/curl-request.adoc[]
[[resources-crud-access]]
[[resources-crud-post]]
=== Accessing the crud POST
A `POST` request is used to access the CRUD create
A `POST` request is used to access the CRUD create.
==== Response structure
==== Request structure
include::{snippets}/crud-create-example/http-request.adoc[]
@ -147,15 +136,18 @@ include::{snippets}/crud-create-example/http-response.adoc[]
include::{snippets}/crud-create-example/curl-request.adoc[]
[[resources-crud-access]]
[[resources-crud-delete]]
=== Accessing the crud DELETE
A `DELETE` request is used to access the CRUD create
A `DELETE` request is used to access the CRUD delete.
==== Response structure
==== Request structure
include::{snippets}/crud-delete-example/http-request.adoc[]
==== Path Parameters
include::{snippets}/crud-delete-example/path-parameters.adoc[]
==== Example response
include::{snippets}/crud-delete-example/http-response.adoc[]
@ -164,12 +156,12 @@ include::{snippets}/crud-delete-example/http-response.adoc[]
include::{snippets}/crud-delete-example/curl-request.adoc[]
[[resources-crud-access]]
[[resources-crud-patch]]
=== Accessing the crud PATCH
A `PATCH` request is used to access the CRUD create
A `PATCH` request is used to access the CRUD update.
==== Response structure
==== Request structure
include::{snippets}/crud-patch-example/http-request.adoc[]
@ -181,12 +173,12 @@ include::{snippets}/crud-patch-example/http-response.adoc[]
include::{snippets}/crud-patch-example/curl-request.adoc[]
[[resources-crud-access]]
[[resources-crud-put]]
=== Accessing the crud PUT
A `PUT` request is used to access the CRUD create
A `PUT` request is used to access the CRUD update.
==== Response structure
==== Request structure
include::{snippets}/crud-put-example/http-request.adoc[]

43
spring-rest-docs/src/main/java/com/example/CRUDController.java → spring-5/src/main/java/com/baeldung/restdocs/CRUDController.java
View File

@ -1,16 +1,23 @@
package com.example;
package com.baeldung.restdocs;
import static org.springframework.hateoas.mvc.ControllerLinkBuilder.linkTo;
import java.util.ArrayList;
import java.util.List;
import javax.validation.Valid;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PatchMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;
@ -18,38 +25,38 @@ import org.springframework.web.bind.annotation.RestController;
@RequestMapping("/crud")
public class CRUDController {
@RequestMapping(method = RequestMethod.GET)
@ResponseStatus(HttpStatus.OK)
public List<CrudInput> read(@RequestBody CrudInput crudInput) {
List<CrudInput> returnList = new ArrayList<CrudInput>();
@GetMapping
public List<CrudInput> read(@RequestBody @Valid CrudInput crudInput) {
List<CrudInput> returnList = new ArrayList<>();
returnList.add(crudInput);
return returnList;
}
@ResponseStatus(HttpStatus.CREATED)
@RequestMapping(method = RequestMethod.POST)
public HttpHeaders save(@RequestBody CrudInput crudInput) {
@PostMapping
public HttpHeaders save(@RequestBody @Valid CrudInput crudInput) {
HttpHeaders httpHeaders = new HttpHeaders();
httpHeaders.setLocation(linkTo(CRUDController.class).slash(crudInput.getTitle()).toUri());
httpHeaders.setLocation(linkTo(CRUDController.class).slash(crudInput.getId()).toUri());
return httpHeaders;
}
@RequestMapping(value = "/{id}", method = RequestMethod.DELETE)
@DeleteMapping("/{id}")
@ResponseStatus(HttpStatus.OK)
HttpHeaders delete(@RequestBody CrudInput crudInput) {
HttpHeaders httpHeaders = new HttpHeaders();
return httpHeaders;
HttpHeaders delete(@PathVariable("id") long id) {
return new HttpHeaders();
}
@RequestMapping(value = "/{id}", method = RequestMethod.PUT)
@PutMapping("/{id}")
@ResponseStatus(HttpStatus.ACCEPTED)
void put(@PathVariable("id") long id, @RequestBody CrudInput crudInput) {
}
@RequestMapping(value = "/{id}", method = RequestMethod.PATCH)
@ResponseStatus(HttpStatus.NO_CONTENT)
void patch(@PathVariable("id") long id, @RequestBody CrudInput crudInput) {
@PatchMapping("/{id}")
public List<CrudInput> patch(@PathVariable("id") long id, @RequestBody CrudInput crudInput) {
List<CrudInput> returnList = new ArrayList<CrudInput>();
crudInput.setId(id);
returnList.add(crudInput);
return returnList;
}
}

66
spring-5/src/main/java/com/baeldung/restdocs/CrudInput.java Normal file
View File

@ -0,0 +1,66 @@
package com.baeldung.restdocs;
import java.net.URI;
import java.util.Collections;
import java.util.List;
import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotNull;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
public class CrudInput {
@NotNull
private long id;
@NotBlank
private String title;
private String body;
private List<URI> tagUris;
@JsonCreator
public CrudInput(@JsonProperty("id") long id, @JsonProperty("title") String title, @JsonProperty("body") String body, @JsonProperty("tags") List<URI> tagUris) {
this.id=id;
this.title = title;
this.body = body;
this.tagUris = tagUris == null ? Collections.<URI> emptyList() : tagUris;
}
public String getTitle() {
return title;
}
public String getBody() {
return body;
}
public long getId() {
return id;
}
public void setId(long id) {
this.id = id;
}
public void setTitle(String title) {
this.title = title;
}
public void setBody(String body) {
this.body = body;
}
public void setTagUris(List<URI> tagUris) {
this.tagUris = tagUris;
}
@JsonProperty("tags")
public List<URI> getTagUris() {
return this.tagUris;
}
}

6
spring-rest-docs/src/main/java/com/example/IndexController.java → spring-5/src/main/java/com/baeldung/restdocs/IndexController.java
View File

@ -1,17 +1,17 @@
package com.example;
package com.baeldung.restdocs;
import static org.springframework.hateoas.mvc.ControllerLinkBuilder.linkTo;
import org.springframework.hateoas.ResourceSupport;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/")
public class IndexController {
@RequestMapping(method = RequestMethod.GET)
@GetMapping
public ResourceSupport index() {
ResourceSupport index = new ResourceSupport();
index.add(linkTo(CRUDController.class).withRel("crud"));

2
spring-rest-docs/src/main/java/com/example/SpringRestDocsApplication.java → spring-5/src/main/java/com/baeldung/restdocs/SpringRestDocsApplication.java
View File

@ -1,4 +1,4 @@
package com.example;
package com.baeldung.restdocs;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

180
spring-5/src/test/java/com/baeldung/restdocs/ApiDocumentationJUnit4IntegrationTest.java Normal file
View File

@ -0,0 +1,180 @@
package com.baeldung.restdocs;
import com.baeldung.restdocs.CrudInput;
import com.baeldung.restdocs.SpringRestDocsApplication;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.junit.Before;
import org.junit.Rule;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.hateoas.MediaTypes;
import org.springframework.restdocs.JUnitRestDocumentation;
import org.springframework.restdocs.constraints.ConstraintDescriptions;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;
import java.util.HashMap;
import java.util.Map;
import static java.util.Collections.singletonList;
import static org.springframework.restdocs.headers.HeaderDocumentation.headerWithName;
import static org.springframework.restdocs.headers.HeaderDocumentation.responseHeaders;
import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.linkWithRel;
import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.links;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.*;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessRequest;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessResponse;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.prettyPrint;
import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
import static org.springframework.restdocs.payload.PayloadDocumentation.requestFields;
import static org.springframework.restdocs.payload.PayloadDocumentation.responseFields;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import static org.springframework.util.StringUtils.collectionToDelimitedString;
import static org.springframework.restdocs.payload.PayloadDocumentation.subsectionWithPath;
import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
import static org.springframework.restdocs.request.RequestDocumentation.pathParameters;
@RunWith(SpringRunner.class)
@SpringBootTest(classes = SpringRestDocsApplication.class)
public class ApiDocumentationJUnit4IntegrationTest {
@Rule
public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("target/generated-snippets");
@Autowired
private WebApplicationContext context;
@Autowired
private ObjectMapper objectMapper;
private MockMvc mockMvc;
@Before
public void setUp() {
this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
.apply(documentationConfiguration(this.restDocumentation))
.alwaysDo(document("{method-name}", preprocessRequest(prettyPrint()), preprocessResponse(prettyPrint())))
.build();
}
@Test
public void indexExample() throws Exception {
this.mockMvc.perform(get("/"))
.andExpect(status().isOk())
.andDo(document("index-example", preprocessRequest(prettyPrint()), preprocessResponse(prettyPrint()), links(linkWithRel("crud").description("The CRUD resource")), responseFields(subsectionWithPath("_links").description("Links to other resources")),
responseHeaders(headerWithName("Content-Type").description("The Content-Type of the payload, e.g. `application/hal+json`"))));
}
@Test
public void crudGetExample() throws Exception {
Map<String, Object> crud = new HashMap<>();
crud.put("id", 1L);
crud.put("title", "Sample Model");
crud.put("body", "http://www.baeldung.com/");
String tagLocation = this.mockMvc.perform(get("/crud").contentType(MediaTypes.HAL_JSON)
.content(this.objectMapper.writeValueAsString(crud)))
.andExpect(status().isOk())
.andReturn()
.getResponse()
.getHeader("Location");
crud.put("tags", singletonList(tagLocation));
ConstraintDescriptions desc = new ConstraintDescriptions(CrudInput.class);
this.mockMvc.perform(get("/crud").contentType(MediaTypes.HAL_JSON)
.content(this.objectMapper.writeValueAsString(crud)))
.andExpect(status().isOk())
.andDo(document("crud-get-example", preprocessRequest(prettyPrint()), preprocessResponse(prettyPrint()), requestFields(fieldWithPath("id").description("The id of the input" + collectionToDelimitedString(desc.descriptionsForProperty("id"), ". ")),
fieldWithPath("title").description("The title of the input"), fieldWithPath("body").description("The body of the input"), fieldWithPath("tags").description("An array of tag resource URIs"))));
}
@Test
public void crudCreateExample() throws Exception {
Map<String, Object> crud = new HashMap<>();
crud.put("id", 2L);
crud.put("title", "Sample Model");
crud.put("body", "http://www.baeldung.com/");
String tagLocation = this.mockMvc.perform(post("/crud").contentType(MediaTypes.HAL_JSON)
.content(this.objectMapper.writeValueAsString(crud)))
.andExpect(status().isCreated())
.andReturn()
.getResponse()
.getHeader("Location");
crud.put("tags", singletonList(tagLocation));
this.mockMvc.perform(post("/crud").contentType(MediaTypes.HAL_JSON)
.content(this.objectMapper.writeValueAsString(crud)))
.andExpect(status().isCreated())
.andDo(document("crud-create-example", preprocessRequest(prettyPrint()), preprocessResponse(prettyPrint()), requestFields(fieldWithPath("id").description("The id of the input"), fieldWithPath("title").description("The title of the input"),
fieldWithPath("body").description("The body of the input"), fieldWithPath("tags").description("An array of tag resource URIs"))));
}
@Test
public void crudDeleteExample() throws Exception {
this.mockMvc.perform(delete("/crud/{id}", 10))
.andExpect(status().isOk())
.andDo(document("crud-delete-example", pathParameters(parameterWithName("id").description("The id of the input to delete"))));
}
@Test
public void crudPatchExample() throws Exception {
Map<String, String> tag = new HashMap<>();
tag.put("name", "PATCH");
String tagLocation = this.mockMvc.perform(patch("/crud/{id}", 10).contentType(MediaTypes.HAL_JSON)
.content(this.objectMapper.writeValueAsString(tag)))
.andExpect(status().isOk())
.andReturn()
.getResponse()
.getHeader("Location");
Map<String, Object> crud = new HashMap<>();
crud.put("title", "Sample Model Patch");
crud.put("body", "http://www.baeldung.com/");
crud.put("tags", singletonList(tagLocation));
this.mockMvc.perform(patch("/crud/{id}", 10).contentType(MediaTypes.HAL_JSON)
.content(this.objectMapper.writeValueAsString(crud)))
.andExpect(status().isOk());
}
@Test
public void crudPutExample() throws Exception {
Map<String, String> tag = new HashMap<>();
tag.put("name", "PUT");
String tagLocation = this.mockMvc.perform(put("/crud/{id}", 10).contentType(MediaTypes.HAL_JSON)
.content(this.objectMapper.writeValueAsString(tag)))
.andExpect(status().isAccepted())
.andReturn()
.getResponse()
.getHeader("Location");
Map<String, Object> crud = new HashMap<>();
crud.put("title", "Sample Model");
crud.put("body", "http://www.baeldung.com/");
crud.put("tags", singletonList(tagLocation));
this.mockMvc.perform(put("/crud/{id}", 10).contentType(MediaTypes.HAL_JSON)
.content(this.objectMapper.writeValueAsString(crud)))
.andExpect(status().isAccepted());
}
@Test
public void contextLoads() {
}
}

173
spring-5/src/test/java/com/baeldung/restdocs/ApiDocumentationJUnit5IntegrationTest.java Normal file
View File

@ -0,0 +1,173 @@
package com.baeldung.restdocs;
import static java.util.Collections.singletonList;
import static org.springframework.restdocs.headers.HeaderDocumentation.headerWithName;
import static org.springframework.restdocs.headers.HeaderDocumentation.responseHeaders;
import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.linkWithRel;
import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.links;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.*;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessRequest;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessResponse;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.prettyPrint;
import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
import static org.springframework.restdocs.payload.PayloadDocumentation.requestFields;
import static org.springframework.restdocs.payload.PayloadDocumentation.responseFields;
import static org.springframework.restdocs.request.RequestDocumentation.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import static org.springframework.util.StringUtils.collectionToDelimitedString;
import java.util.HashMap;
import java.util.Map;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.hateoas.MediaTypes;
import org.springframework.restdocs.RestDocumentationContextProvider;
import org.springframework.restdocs.RestDocumentationExtension;
import org.springframework.restdocs.constraints.ConstraintDescriptions;
import static org.springframework.restdocs.payload.PayloadDocumentation.subsectionWithPath;
import org.springframework.test.context.junit.jupiter.SpringExtension;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;
import com.baeldung.restdocs.CrudInput;
import com.baeldung.restdocs.SpringRestDocsApplication;
import com.fasterxml.jackson.databind.ObjectMapper;
@ExtendWith({ RestDocumentationExtension.class, SpringExtension.class })
@SpringBootTest(classes = SpringRestDocsApplication.class)
public class ApiDocumentationJUnit5IntegrationTest {
@Autowired
private ObjectMapper objectMapper;
private MockMvc mockMvc;
@BeforeEach
public void setUp(WebApplicationContext webApplicationContext, RestDocumentationContextProvider restDocumentation) {
this.mockMvc = MockMvcBuilders.webAppContextSetup(webApplicationContext)
.apply(documentationConfiguration(restDocumentation))
.alwaysDo(document("{method-name}", preprocessRequest(prettyPrint()), preprocessResponse(prettyPrint())))
.build();
}
@Test
public void indexExample() throws Exception {
this.mockMvc.perform(get("/"))
.andExpect(status().isOk())
.andDo(document("index-example", preprocessRequest(prettyPrint()), preprocessResponse(prettyPrint()), links(linkWithRel("crud").description("The CRUD resource")), responseFields(subsectionWithPath("_links").description("Links to other resources")),
responseHeaders(headerWithName("Content-Type").description("The Content-Type of the payload, e.g. `application/hal+json`"))));
}
@Test
public void crudGetExample() throws Exception {
Map<String, Object> crud = new HashMap<>();
crud.put("id", 1L);
crud.put("title", "Sample Model");
crud.put("body", "http://www.baeldung.com/");
String tagLocation = this.mockMvc.perform(get("/crud").contentType(MediaTypes.HAL_JSON)
.content(this.objectMapper.writeValueAsString(crud)))
.andExpect(status().isOk())
.andReturn()
.getResponse()
.getHeader("Location");
crud.put("tags", singletonList(tagLocation));
ConstraintDescriptions desc = new ConstraintDescriptions(CrudInput.class);
this.mockMvc.perform(get("/crud").contentType(MediaTypes.HAL_JSON)
.content(this.objectMapper.writeValueAsString(crud)))
.andExpect(status().isOk())
.andDo(document("crud-get-example", preprocessRequest(prettyPrint()), preprocessResponse(prettyPrint()), requestFields(fieldWithPath("id").description("The id of the input" + collectionToDelimitedString(desc.descriptionsForProperty("id"), ". ")),
fieldWithPath("title").description("The title of the input"), fieldWithPath("body").description("The body of the input"), fieldWithPath("tags").description("An array of tag resource URIs"))));
}
@Test
public void crudCreateExample() throws Exception {
Map<String, Object> crud = new HashMap<>();
crud.put("id", 2L);
crud.put("title", "Sample Model");
crud.put("body", "http://www.baeldung.com/");
String tagLocation = this.mockMvc.perform(post("/crud").contentType(MediaTypes.HAL_JSON)
.content(this.objectMapper.writeValueAsString(crud)))
.andExpect(status().isCreated())
.andReturn()
.getResponse()
.getHeader("Location");
crud.put("tags", singletonList(tagLocation));
this.mockMvc.perform(post("/crud").contentType(MediaTypes.HAL_JSON)
.content(this.objectMapper.writeValueAsString(crud)))
.andExpect(status().isCreated())
.andDo(document("crud-create-example", preprocessRequest(prettyPrint()), preprocessResponse(prettyPrint()), requestFields(fieldWithPath("id").description("The id of the input"), fieldWithPath("title").description("The title of the input"),
fieldWithPath("body").description("The body of the input"), fieldWithPath("tags").description("An array of tag resource URIs"))));
}
@Test
public void crudDeleteExample() throws Exception {
this.mockMvc.perform(delete("/crud/{id}", 10))
.andExpect(status().isOk())
.andDo(document("crud-delete-example", pathParameters(parameterWithName("id").description("The id of the input to delete"))));
}
@Test
public void crudPatchExample() throws Exception {
Map<String, String> tag = new HashMap<>();
tag.put("name", "PATCH");
String tagLocation = this.mockMvc.perform(patch("/crud/{id}", 10).contentType(MediaTypes.HAL_JSON)
.content(this.objectMapper.writeValueAsString(tag)))
.andExpect(status().isOk())
.andReturn()
.getResponse()
.getHeader("Location");
Map<String, Object> crud = new HashMap<>();
crud.put("title", "Sample Model Patch");
crud.put("body", "http://www.baeldung.com/");
crud.put("tags", singletonList(tagLocation));
this.mockMvc.perform(patch("/crud/{id}", 10).contentType(MediaTypes.HAL_JSON)
.content(this.objectMapper.writeValueAsString(crud)))
.andExpect(status().isOk());
}
@Test
public void crudPutExample() throws Exception {
Map<String, String> tag = new HashMap<>();
tag.put("name", "PUT");
String tagLocation = this.mockMvc.perform(put("/crud/{id}", 10).contentType(MediaTypes.HAL_JSON)
.content(this.objectMapper.writeValueAsString(tag)))
.andExpect(status().isAccepted())
.andReturn()
.getResponse()
.getHeader("Location");
Map<String, Object> crud = new HashMap<>();
crud.put("title", "Sample Model");
crud.put("body", "http://www.baeldung.com/");
crud.put("tags", singletonList(tagLocation));
this.mockMvc.perform(put("/crud/{id}", 10).contentType(MediaTypes.HAL_JSON)
.content(this.objectMapper.writeValueAsString(crud)))
.andExpect(status().isAccepted());
}
@Test
public void contextLoads() {
}
}

5
spring-rest-docs/README.MD
View File

@ -1,5 +0,0 @@
###The Course
The "REST With Spring" Classes: http://bit.ly/restwithspring
###Relevant Articles:
- [Introduction to Spring REST Docs](http://www.baeldung.com/spring-rest-docs)

112
spring-rest-docs/pom.xml
View File

@ -1,112 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>spring-rest-docs</artifactId>
<version>0.0.1-SNAPSHOT</version>
<packaging>jar</packaging>
<name>spring-rest-docs</name>
<description>Demo project for Spring Boot</description>
<parent>
<artifactId>parent-boot-5</artifactId>
<groupId>com.baeldung</groupId>
<version>0.0.1-SNAPSHOT</version>
<relativePath>../parent-boot-5</relativePath>
</parent>
<properties>
<snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
<restdocs.version>1.1.2.RELEASE</restdocs.version>
<jsonpath.version>2.2.0</jsonpath.version>
<asciidoctor-plugin.version>1.5.3</asciidoctor-plugin.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-hateoas</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.restdocs</groupId>
<artifactId>spring-restdocs-mockmvc</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>com.jayway.jsonpath</groupId>
<artifactId>json-path</artifactId>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>${asciidoctor-plugin.version}</version>
<executions>
<execution>
<id>generate-docs</id>
<phase>package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html</backend>
<doctype>book</doctype>
<attributes>
<snippets>${snippetsDirectory}</snippets>
</attributes>
<sourceDirectory>src/docs/asciidocs</sourceDirectory>
<outputDirectory>target/generated-docs</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
<profiles>
<profile>
<id>integration</id>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<executions>
<execution>
<phase>integration-test</phase>
<goals>
<goal>test</goal>
</goals>
<configuration>
<excludes>
<exclude>**/*LiveTest.java</exclude>
</excludes>
<includes>
<include>**/*IntegrationTest.java</include>
</includes>
</configuration>
</execution>
</executions>
<configuration>
<systemPropertyVariables>
<test.mime>json</test.mime>
</systemPropertyVariables>
</configuration>
</plugin>
</plugins>
</build>
</profile>
</profiles>
</project>

41
spring-rest-docs/src/main/java/com/example/CrudInput.java
View File

@ -1,41 +0,0 @@
package com.example;
import java.net.URI;
import java.util.Collections;
import java.util.List;
import org.hibernate.validator.constraints.NotBlank;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
public class CrudInput {
// @NotBlank
private final String title;
private final String body;
private final List<URI> tagUris;
@JsonCreator
public CrudInput(@JsonProperty("title") String title, @JsonProperty("body") String body, @JsonProperty("tags") List<URI> tagUris) {
this.title = title;
this.body = body;
this.tagUris = tagUris == null ? Collections.<URI> emptyList() : tagUris;
}
public String getTitle() {
return title;
}
public String getBody() {
return body;
}
@JsonProperty("tags")
public List<URI> getTagUris() {
return this.tagUris;
}
}

0
spring-rest-docs/src/main/resources/application.properties
View File

181
spring-rest-docs/src/test/java/com/example/ApiDocumentationIntegrationTest.java
View File

@ -1,181 +0,0 @@
package com.example;
import static java.util.Collections.singletonList;
import static org.springframework.restdocs.headers.HeaderDocumentation.headerWithName;
import static org.springframework.restdocs.headers.HeaderDocumentation.responseHeaders;
import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.linkWithRel;
import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.links;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.delete;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.patch;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.post;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.put;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessRequest;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessResponse;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.prettyPrint;
import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
import static org.springframework.restdocs.payload.PayloadDocumentation.requestFields;
import static org.springframework.restdocs.payload.PayloadDocumentation.responseFields;
import static org.springframework.restdocs.snippet.Attributes.key;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import static org.springframework.util.StringUtils.collectionToDelimitedString;
import java.util.HashMap;
import java.util.Map;
import org.junit.Before;
import org.junit.Rule;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.hateoas.MediaTypes;
import org.springframework.restdocs.RestDocumentation;
import org.springframework.restdocs.constraints.ConstraintDescriptions;
import org.springframework.restdocs.mockmvc.RestDocumentationResultHandler;
import org.springframework.restdocs.payload.FieldDescriptor;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
import org.springframework.test.context.web.WebAppConfiguration;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;
import com.fasterxml.jackson.databind.ObjectMapper;
@RunWith(SpringJUnit4ClassRunner.class)
@SpringBootTest(classes = SpringRestDocsApplication.class)
@WebAppConfiguration
public class ApiDocumentationIntegrationTest {
@Rule
public final RestDocumentation restDocumentation = new RestDocumentation("target/generated-snippets");
@Autowired
private WebApplicationContext context;
@Autowired
private ObjectMapper objectMapper;
private RestDocumentationResultHandler document;
private MockMvc mockMvc;
@Before
public void setUp() {
this.document = document("{method-name}", preprocessRequest(prettyPrint()), preprocessResponse(prettyPrint()));
this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context).apply(documentationConfiguration(this.restDocumentation)).alwaysDo(this.document).build();
}
@Test
public void headersExample() throws Exception {
this.document.snippets(responseHeaders(headerWithName("Content-Type").description("The Content-Type of the payload, e.g. `application/hal+json`")));
this.mockMvc.perform(get("/")).andExpect(status().isOk());
}
@Test
public void indexExample() throws Exception {
this.document.snippets(links(linkWithRel("crud").description("The <<resources-tags,Tags resource>>")), responseFields(fieldWithPath("_links").description("<<resources-index-links,Links>> to other resources")));
this.mockMvc.perform(get("/")).andExpect(status().isOk());
}
@Test
public void crudGetExample() throws Exception {
Map<String, String> tag = new HashMap<>();
tag.put("name", "GET");
String tagLocation = this.mockMvc.perform(get("/crud").contentType(MediaTypes.HAL_JSON).content(this.objectMapper.writeValueAsString(tag))).andExpect(status().isOk()).andReturn().getResponse().getHeader("Location");
Map<String, Object> crud = new HashMap<>();
crud.put("title", "Sample Model");
crud.put("body", "http://www.baeldung.com/");
crud.put("tags", singletonList(tagLocation));
this.mockMvc.perform(get("/crud").contentType(MediaTypes.HAL_JSON).content(this.objectMapper.writeValueAsString(crud))).andExpect(status().isOk());
}
@Test
public void crudCreateExample() throws Exception {
Map<String, String> tag = new HashMap<>();
tag.put("name", "CREATE");
String tagLocation = this.mockMvc.perform(post("/crud").contentType(MediaTypes.HAL_JSON).content(this.objectMapper.writeValueAsString(tag))).andExpect(status().isCreated()).andReturn().getResponse().getHeader("Location");
Map<String, Object> crud = new HashMap<>();
crud.put("title", "Sample Model");
crud.put("body", "http://www.baeldung.com/");
crud.put("tags", singletonList(tagLocation));
ConstrainedFields fields = new ConstrainedFields(CrudInput.class);
this.document.snippets(requestFields(fields.withPath("title").description("The title of the note"), fields.withPath("body").description("The body of the note"), fields.withPath("tags").description("An array of tag resource URIs")));
this.mockMvc.perform(post("/crud").contentType(MediaTypes.HAL_JSON).content(this.objectMapper.writeValueAsString(crud))).andExpect(status().isCreated());
}
@Test
public void crudDeleteExample() throws Exception {
Map<String, String> tag = new HashMap<>();
tag.put("name", "DELETE");
String tagLocation = this.mockMvc.perform(delete("/crud/10").contentType(MediaTypes.HAL_JSON).content(this.objectMapper.writeValueAsString(tag))).andExpect(status().isOk()).andReturn().getResponse().getHeader("Location");
Map<String, Object> crud = new HashMap<>();
crud.put("title", "Sample Model");
crud.put("body", "http://www.baeldung.com/");
crud.put("tags", singletonList(tagLocation));
this.mockMvc.perform(delete("/crud/10").contentType(MediaTypes.HAL_JSON).content(this.objectMapper.writeValueAsString(crud))).andExpect(status().isOk());
}
@Test
public void crudPatchExample() throws Exception {
Map<String, String> tag = new HashMap<>();
tag.put("name", "PATCH");
String tagLocation = this.mockMvc.perform(patch("/crud/10").contentType(MediaTypes.HAL_JSON).content(this.objectMapper.writeValueAsString(tag))).andExpect(status().isNoContent()).andReturn().getResponse().getHeader("Location");
Map<String, Object> crud = new HashMap<>();
crud.put("title", "Sample Model");
crud.put("body", "http://www.baeldung.com/");
crud.put("tags", singletonList(tagLocation));
this.mockMvc.perform(patch("/crud/10").contentType(MediaTypes.HAL_JSON).content(this.objectMapper.writeValueAsString(crud))).andExpect(status().isNoContent());
}
@Test
public void crudPutExample() throws Exception {
Map<String, String> tag = new HashMap<>();
tag.put("name", "PUT");
String tagLocation = this.mockMvc.perform(put("/crud/10").contentType(MediaTypes.HAL_JSON).content(this.objectMapper.writeValueAsString(tag))).andExpect(status().isAccepted()).andReturn().getResponse().getHeader("Location");
Map<String, Object> crud = new HashMap<>();
crud.put("title", "Sample Model");
crud.put("body", "http://www.baeldung.com/");
crud.put("tags", singletonList(tagLocation));
this.mockMvc.perform(put("/crud/10").contentType(MediaTypes.HAL_JSON).content(this.objectMapper.writeValueAsString(crud))).andExpect(status().isAccepted());
}
@Test
public void contextLoads() {
}
private static class ConstrainedFields {
private final ConstraintDescriptions constraintDescriptions;
ConstrainedFields(Class<?> input) {
this.constraintDescriptions = new ConstraintDescriptions(input);
}
private FieldDescriptor withPath(String path) {
return fieldWithPath(path).attributes(key("constraints").value(collectionToDelimitedString(this.constraintDescriptions.descriptionsForProperty(path), ". ")));
}
}
}

147
spring-rest-docs/src/test/java/com/example/GettingStartedDocumentationIntegrationTest.java
View File

@ -1,147 +0,0 @@
package com.example;
import static org.hamcrest.Matchers.is;
import static org.hamcrest.Matchers.notNullValue;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessRequest;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessResponse;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.prettyPrint;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import org.junit.Before;
import org.junit.Rule;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.hateoas.MediaTypes;
import org.springframework.restdocs.RestDocumentation;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
import org.springframework.test.context.web.WebAppConfiguration;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;
import com.fasterxml.jackson.databind.ObjectMapper;
@RunWith(SpringJUnit4ClassRunner.class)
@SpringBootTest(classes = SpringRestDocsApplication.class)
@WebAppConfiguration
public class GettingStartedDocumentationIntegrationTest {
@Rule
public final RestDocumentation restDocumentation = new RestDocumentation("target/generated-snippets");
@Autowired
private ObjectMapper objectMapper;
@Autowired
private WebApplicationContext context;
private MockMvc mockMvc;
@Before
public void setUp() {
this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context).apply(documentationConfiguration(this.restDocumentation)).alwaysDo(document("{method-name}/{step}/", preprocessRequest(prettyPrint()), preprocessResponse(prettyPrint()))).build();
}
@Test
public void index() throws Exception {
this.mockMvc.perform(get("/").accept(MediaTypes.HAL_JSON)).andExpect(status().isOk()).andExpect(jsonPath("_links.crud", is(notNullValue()))).andExpect(jsonPath("_links.crud", is(notNullValue())));
}
// String createNote() throws Exception {
// Map<String, String> note = new HashMap<String, String>();
// note.put("title", "Note creation with cURL");
// note.put("body", "An example of how to create a note using curl");
// String noteLocation = this.mockMvc.perform(post("/crud")
// .contentType(MediaTypes.HAL_JSON)
// .content(objectMapper.writeValueAsString(note)))
// .andExpect(status().isCreated())
// .andExpect(header().string("Location", notNullValue()))
// .andReturn()
// .getResponse()
// .getHeader("Location");
// return noteLocation;
// }
//
// MvcResult getNote(String noteLocation) throws Exception {
// return this.mockMvc.perform(get(noteLocation))
// .andExpect(status().isOk())
// .andExpect(jsonPath("title", is(notNullValue())))
// .andExpect(jsonPath("body", is(notNullValue())))
// .andExpect(jsonPath("_links.crud", is(notNullValue())))
// .andReturn();
// }
//
//
// String createTag() throws Exception, JsonProcessingException {
// Map<String, String> tag = new HashMap<String, String>();
// tag.put("name", "getting-started");
// String tagLocation = this.mockMvc.perform(post("/crud")
// .contentType(MediaTypes.HAL_JSON)
// .content(objectMapper.writeValueAsString(tag)))
// .andExpect(status().isCreated())
// .andExpect(header().string("Location", notNullValue()))
// .andReturn()
// .getResponse()
// .getHeader("Location");
// return tagLocation;
// }
//
// void getTag(String tagLocation) throws Exception {
// this.mockMvc.perform(get(tagLocation)).andExpect(status().isOk())
// .andExpect(jsonPath("name", is(notNullValue())))
// .andExpect(jsonPath("_links.tagged-notes", is(notNullValue())));
// }
//
// String createTaggedNote(String tag) throws Exception {
// Map<String, Object> note = new HashMap<String, Object>();
// note.put("title", "Tagged note creation with cURL");
// note.put("body", "An example of how to create a tagged note using cURL");
// note.put("tags", Arrays.asList(tag));
//
// String noteLocation = this.mockMvc.perform(post("/notes")
// .contentType(MediaTypes.HAL_JSON)
// .content(objectMapper.writeValueAsString(note)))
// .andExpect(status().isCreated())
// .andExpect(header().string("Location", notNullValue()))
// .andReturn()
// .getResponse()
// .getHeader("Location");
// return noteLocation;
// }
//
// void getTags(String noteTagsLocation) throws Exception {
// this.mockMvc.perform(get(noteTagsLocation))
// .andExpect(status().isOk())
// .andExpect(jsonPath("_embedded.tags", hasSize(1)));
// }
//
// void tagExistingNote(String noteLocation, String tagLocation) throws Exception {
// Map<String, Object> update = new HashMap<String, Object>();
// update.put("tags", Arrays.asList(tagLocation));
// this.mockMvc.perform(patch(noteLocation)
// .contentType(MediaTypes.HAL_JSON)
// .content(objectMapper.writeValueAsString(update)))
// .andExpect(status().isNoContent());
// }
//
// MvcResult getTaggedExistingNote(String noteLocation) throws Exception {
// return this.mockMvc.perform(get(noteLocation)).andExpect(status().isOk()).andReturn();
// }
//
// void getTagsForExistingNote(String noteTagsLocation) throws Exception {
// this.mockMvc.perform(get(noteTagsLocation))
// .andExpect(status().isOk()).andExpect(jsonPath("_embedded.tags", hasSize(1)));
// }
//
// private String getLink(MvcResult result, String rel)
// throws UnsupportedEncodingException {
// return JsonPath.parse(result.getResponse().getContentAsString()).read("_links." + rel + ".href");
// }
}