BAEL-3493: Spring REST Docs vs OpenAPI (#9295)

spring-boot-modules/spring-boot-springdoc/pom.xml

@@ -37,7 +37,7 @@
             <scope>test</scope>
         </dependency>
 
-        <dependency>
+       <dependency>
             <groupId>org.hibernate</groupId>
             <artifactId>hibernate-core</artifactId>
             <version>${hibernate.version}</version>
@@ -53,7 +53,19 @@
             <groupId>org.springdoc</groupId>
             <artifactId>springdoc-openapi-data-rest</artifactId>
             <version>${springdoc.version}</version>
+        </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-restassured</artifactId>
+            <scope>test</scope>
+        </dependency> 
     </dependencies>
 
     <build>
@@ -62,13 +74,49 @@
                 <groupId>org.springframework.boot</groupId>
                 <artifactId>spring-boot-maven-plugin</artifactId>
             </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/main/resources/asciidocs</sourceDirectory>
+                            <outputDirectory>target/generated-docs</outputDirectory>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
         </plugins>
+        <resources>
+            <resource>
+                <filtering>true</filtering>
+                <directory>src/main/resources</directory>
+                <includes>
+                    <include>application.properties</include>
+                    <include>data.sql</include>
+                   <include>schema.sql</include>
+                </includes>
+            </resource>
+        </resources>
     </build>
 
     <properties>
         <java.version>1.8</java.version>
         <hibernate.version>5.2.10.Final</hibernate.version>
         <springdoc.version>1.2.32</springdoc.version>
+        <asciidoctor-plugin.version>1.5.6</asciidoctor-plugin.version>
+        <snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
     </properties>
 
     <profiles>

spring-boot-modules/spring-boot-springdoc/src/main/java/com/baeldung/restdocopenapi/Application.java

@@ -0,0 +1,28 @@
+package com.baeldung.restdocopenapi;
+
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.context.annotation.Bean;
+
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.info.Info;
+import io.swagger.v3.oas.models.info.License;
+
+@SpringBootApplication()
+public class Application {
+
+    public static void main(String[] args) {
+        SpringApplication.run(Application.class, args);
+    }
+
+    @Bean
+    public OpenAPI customOpenAPI(@Value("${springdoc.version}") String appVersion) {
+        return new OpenAPI().info(new Info().title("Foobar API")
+            .version(appVersion)
+            .description("This is a sample Foobar server created using springdocs - a library for OpenAPI 3 with spring boot.")
+            .termsOfService("http://swagger.io/terms/")
+            .license(new License().name("Apache 2.0")
+                .url("http://springdoc.org")));
+    }
+}

spring-boot-modules/spring-boot-springdoc/src/main/java/com/baeldung/restdocopenapi/Foo.java

@@ -0,0 +1,93 @@
+package com.baeldung.restdocopenapi;
+
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.GeneratedValue;
+import javax.persistence.GenerationType;
+import javax.persistence.Id;
+
+@Entity
+public class Foo {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(nullable = false)
+    private String title;
+    
+    @Column()
+    private String body;
+
+
+    protected Foo() {
+    }
+
+    public Foo(long id, String title, String body) {
+        this.id = id;
+        this.title = title;
+        this.body = body;
+    }
+
+    public Long getId() {
+        return id;
+    }
+
+    public void setId(Long id) {
+        this.id = id;
+    }
+
+    public String getTitle() {
+        return title;
+    }
+
+    public void setTitle(String title) {
+        this.title = title;
+    }
+
+    public String getBody() {
+        return body;
+    }
+
+    public void setBody(String body) {
+        this.body = body;
+    }
+
+
+    @Override
+    public int hashCode() {
+        final int prime = 31;
+        int result = 1;
+        result = prime * result;
+        result = prime * result + ((id == null) ? 0 : id.hashCode());
+        result = prime * result + ((title == null) ? 0 : title.hashCode());
+        return result;
+    }
+    
+    @Override
+    public boolean equals(Object obj) {
+        if (this == obj)
+            return true;
+        if (obj == null)
+            return false;
+        if (getClass() != obj.getClass())
+            return false;
+        Foo other = (Foo) obj;
+        if (id == null) {
+            if (other.id != null)
+                return false;
+        } else if (!id.equals(other.id))
+            return false;
+        if (title == null) {
+            if (other.title != null)
+                return false;
+        } else if (!title.equals(other.title))
+            return false;
+        return true;
+    }
+    
+    @Override
+    public String toString() {
+        return "Foo [id=" + id + ", title=" + title + "]";
+    }
+}

spring-boot-modules/spring-boot-springdoc/src/main/java/com/baeldung/restdocopenapi/FooController.java

@@ -0,0 +1,83 @@
+package com.baeldung.restdocopenapi;
+
+import static org.springframework.hateoas.server.mvc.WebMvcLinkBuilder.linkTo;
+
+import java.util.List;
+import java.util.Optional;
+
+import javax.validation.Valid;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+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.RestController;
+
+@RestController
+@RequestMapping("/foo")
+public class FooController {
+
+    @Autowired
+    FooRepository repository;
+
+    @GetMapping
+    public ResponseEntity<List<Foo>> getAllFoos() {
+        List<Foo> fooList = (List<Foo>) repository.findAll();
+        if (fooList.isEmpty()) {
+            return new ResponseEntity<>(HttpStatus.NOT_FOUND);
+        }
+        return new ResponseEntity<>(fooList, HttpStatus.OK);
+    }
+
+    @GetMapping(value = "{id}")
+    public ResponseEntity<Foo> getFooById(@PathVariable("id") Long id) {
+
+        Optional<Foo> foo = repository.findById(id);
+        return foo.isPresent() ? new ResponseEntity<>(foo.get(), HttpStatus.OK) : new ResponseEntity<>(HttpStatus.NOT_FOUND);
+    }
+
+    @PostMapping
+    public ResponseEntity<Foo> addFoo(@RequestBody @Valid Foo foo) {
+        HttpHeaders httpHeaders = new HttpHeaders();
+        httpHeaders.setLocation(linkTo(FooController.class).slash(foo.getId())
+            .toUri());
+        Foo savedFoo;
+        try {
+            savedFoo = repository.save(foo);
+        } catch (Exception e) {
+            return new ResponseEntity<>(HttpStatus.BAD_REQUEST);
+        }
+
+        return new ResponseEntity<>(savedFoo, httpHeaders, HttpStatus.CREATED);
+    }
+
+    @DeleteMapping("/{id}")
+    public ResponseEntity<Void> deleteFoo(@PathVariable("id") long id) {
+        try {
+            repository.deleteById(id);
+        } catch (Exception e) {
+            return new ResponseEntity<>(HttpStatus.BAD_REQUEST);
+        }
+        return new ResponseEntity<>(HttpStatus.NO_CONTENT);
+    }
+
+    @PutMapping("/{id}")
+    public ResponseEntity<Foo> updateFoo(@PathVariable("id") long id, @RequestBody Foo foo) {
+        boolean isFooPresent = repository.existsById(Long.valueOf(id));
+
+        if (!isFooPresent) {
+            return new ResponseEntity<>(HttpStatus.NOT_FOUND);
+        }
+
+        Foo updatedFoo = repository.save(foo);
+
+        return new ResponseEntity<>(updatedFoo, HttpStatus.OK);
+    }
+}

spring-boot-modules/spring-boot-springdoc/src/main/java/com/baeldung/restdocopenapi/FooRepository.java

@@ -0,0 +1,9 @@
+package com.baeldung.restdocopenapi;
+
+import org.springframework.data.repository.PagingAndSortingRepository;
+import org.springframework.stereotype.Repository;
+
+@Repository
+public interface FooRepository extends PagingAndSortingRepository<Foo, Long>{
+
+}

spring-boot-modules/spring-boot-springdoc/src/main/java/com/baeldung/restdocopenapi/springdoc/FooBarController.java

@@ -0,0 +1,121 @@
+package com.baeldung.restdocopenapi.springdoc;
+
+import static org.springframework.hateoas.server.mvc.WebMvcLinkBuilder.linkTo;
+
+import java.util.List;
+import java.util.Optional;
+
+import javax.validation.Valid;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+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.RestController;
+
+import com.baeldung.restdocopenapi.Foo;
+import com.baeldung.restdocopenapi.FooRepository;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+@RestController
+@RequestMapping("/foobar")
+@Tag(name = "foobar", description = "the foobar API with documentation annotations")
+public class FooBarController {
+
+    @Autowired
+    FooRepository repository;
+
+    @Operation(summary = "Get all foos")
+    @ApiResponses(value = { 
+            @ApiResponse(responseCode = "200", description = "found foos", content = { 
+                @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = Foo.class)))}), 
+            @ApiResponse(responseCode = "404", description = "No Foos found", content = @Content) })
+    @GetMapping
+    public ResponseEntity<List<Foo>> getAllFoos() {
+        List<Foo> fooList = (List<Foo>) repository.findAll();
+        if (fooList.isEmpty()) {
+            return new ResponseEntity<>(HttpStatus.NOT_FOUND);
+        }
+        return new ResponseEntity<>(fooList, HttpStatus.OK);
+    }
+
+    @Operation(summary = "Get a foo by foo id")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "found the foo", content = { 
+                    @Content(mediaType = "application/json", schema = @Schema(implementation = Foo.class))}),
+            @ApiResponse(responseCode = "400", description = "Invalid id supplied", content = @Content), 
+            @ApiResponse(responseCode = "404", description = "Foo not found", content = @Content) })
+    @GetMapping(value = "{id}")
+    public ResponseEntity<Foo> getFooById(@Parameter(description = "id of foo to be searched") @PathVariable("id") String id) {
+
+        Optional<Foo> foo = repository.findById(Long.valueOf(id));
+        return foo.isPresent() ? new ResponseEntity<>(foo.get(), HttpStatus.OK) : new ResponseEntity<>(HttpStatus.NOT_FOUND);
+    }
+
+    @Operation(summary = "Create a foo")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "201", description = "foo created", content = { @
+                    Content(mediaType = "application/json", schema = @Schema(implementation = Foo.class))}),
+            @ApiResponse(responseCode = "404", description = "Bad request", content = @Content) })
+    @PostMapping
+    public ResponseEntity<Foo> addFoo(@Parameter(description = "foo object to be created") @RequestBody @Valid Foo foo) {
+        HttpHeaders httpHeaders = new HttpHeaders();
+        httpHeaders.setLocation(linkTo(FooBarController.class).slash(foo.getId()).toUri());
+        Foo savedFoo;
+        try {
+            savedFoo = repository.save(foo);
+        } catch (Exception e) {
+            return new ResponseEntity<>(HttpStatus.BAD_REQUEST);
+        }
+
+        return new ResponseEntity<>(savedFoo, httpHeaders, HttpStatus.CREATED);
+    }
+
+    @Operation(summary = "Delete a foo")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "204", description = "foo deleted"),
+            @ApiResponse(responseCode = "404", description = "Bad request", content = @Content) })
+    @DeleteMapping("/{id}")
+    public ResponseEntity<Void> deleteFoo(@Parameter(description = "id of foo to be deleted") @PathVariable("id") long id) {
+        try {
+            repository.deleteById(id);
+        } catch (Exception e) {
+            return new ResponseEntity<>(HttpStatus.BAD_REQUEST);
+        }
+        return new ResponseEntity<>(HttpStatus.NO_CONTENT);
+    }
+
+    @Operation(summary = "Update a foo")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "foo updated successfully", content = {
+                    @Content(mediaType = "application/json", schema = @Schema(implementation = Foo.class))}),
+            @ApiResponse(responseCode = "404", description = "No Foo exists with given id", content = @Content) })
+    @PutMapping("/{id}")
+    public ResponseEntity<Foo> updateFoo(@Parameter(description = "id of foo to be updated") @PathVariable("id") long id, @RequestBody Foo foo) {
+        
+        boolean isFooPresent = repository.existsById(Long.valueOf(id));
+
+        if (!isFooPresent) {
+            return new ResponseEntity<>(HttpStatus.NOT_FOUND);
+        }
+        
+        Foo updatedFoo = repository.save(foo);
+
+        return new ResponseEntity<>(updatedFoo, HttpStatus.OK);
+    }
+}

spring-boot-modules/spring-boot-springdoc/src/main/resources/application.properties

@@ -5,4 +5,7 @@ springdoc.swagger-ui.path=/swagger-ui-custom.html
 springdoc.api-docs.path=/api-docs
 
 # H2 Related Configurations
-spring.datasource.url=jdbc:h2:mem:springdoc
+spring.datasource.url=jdbc:h2:mem:springdoc
+
+springdoc.version=@springdoc.version@
+spring.jpa.hibernate.ddl-auto=none

spring-boot-modules/spring-boot-springdoc/src/main/resources/asciidocs/fooapi.adoc

@@ -0,0 +1,153 @@
+= RESTful Notes API Guide
+Baeldung;
+:doctype: book
+:icons: font
+:source-highlighter: highlightjs
+:toc: left
+:toclevels: 4
+:sectlinks:
+
+[[overview]]
+= Overview
+
+[[overview-http-verbs]]
+== HTTP verbs
+
+RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its
+use of HTTP verbs.
+
+|===
+| Verb | Usage
+
+| `GET`
+| Used to retrieve a resource
+
+| `POST`
+| Used to create a new resource
+
+| `PUT`
+| Used to update an existing resource
+
+| `DELETE`
+| Used to delete an existing resource
+|===
+
+RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its
+use of HTTP status codes.
+
+|===
+| Status code | Usage
+
+| `200 OK`
+| The request completed successfully
+
+| `201 Created`
+| A new resource has been created successfully. The resource's URI is available from the response's
+`Location` header
+
+| `204 No Content`
+| An update to an existing resource has been applied successfully
+
+| `400 Bad Request`
+| The request was malformed. The response body will include an error providing further information
+
+| `404 Not Found`
+| The requested resource did not exist
+|===
+
+[[overview-hypermedia]]
+== Hypermedia
+
+RESTful Notes uses hypermedia and resources include links to other resources in their
+responses. Responses are in http://stateless.co/hal_specification.html[Hypertext Application
+from resource to resource.
+Language (HAL)] format. Links can be found beneath the `_links` key. Users of the API should
+not create URIs themselves, instead they should use the above-described links to navigate
+
+[[resources]]
+= Resources
+
+[[resources-FOO]]
+== FOO REST Service 
+
+The FOO provides the entry point into the service.
+
+[[resources-foo-get]]
+=== Accessing the foo GET
+
+A `GET` request is used to access the foo read.
+
+==== Request structure
+
+include::{snippets}/getAFoo/http-request.adoc[]
+
+==== Path Parameters
+include::{snippets}/getAFoo/path-parameters.adoc[]
+
+==== Example response
+
+include::{snippets}/getAFoo/http-response.adoc[]
+
+==== CURL request
+
+include::{snippets}/getAFoo/curl-request.adoc[]
+
+[[resources-foo-post]]
+=== Accessing the foo POST
+
+A `POST` request is used to access the foo create.
+
+==== Request structure
+
+include::{snippets}/createFoo/http-request.adoc[]
+
+==== Example response
+
+include::{snippets}/createFoo/http-response.adoc[]
+
+==== CURL request
+
+include::{snippets}/createFoo/curl-request.adoc[]
+
+[[resources-foo-delete]]
+=== Accessing the foo DELETE
+
+A `DELETE` request is used to access the foo delete.
+
+==== Request structure
+
+include::{snippets}/deleteFoo/http-request.adoc[]
+
+==== Path Parameters
+include::{snippets}/deleteFoo/path-parameters.adoc[]
+
+==== Example response
+
+include::{snippets}/deleteFoo/http-response.adoc[]
+
+==== CURL request
+
+include::{snippets}/deleteFoo/curl-request.adoc[]
+
+[[resources-foo-put]]
+=== Accessing the foo PUT
+
+A `PUT` request is used to access the foo update.
+
+==== Request structure
+
+include::{snippets}/updateFoo/http-request.adoc[]
+
+==== Path Parameters
+include::{snippets}/updateFoo/path-parameters.adoc[]
+
+==== Example response
+
+include::{snippets}/updateFoo/http-response.adoc[]
+
+==== CURL request
+
+include::{snippets}/updateFoo/curl-request.adoc[]
+
+
+

spring-boot-modules/spring-boot-springdoc/src/main/resources/data.sql

@@ -0,0 +1,4 @@
+INSERT INTO Foo(id, title, body) VALUES (1, 'Foo 1', 'Foo body 1');
+INSERT INTO Foo(id, title, body) VALUES (2, 'Foo 2', 'Foo body 2');
+INSERT INTO Foo(id, title, body) VALUES (3, 'Foo 3', 'Foo body 3');
+

spring-boot-modules/spring-boot-springdoc/src/main/resources/schema.sql

@@ -0,0 +1,8 @@
+DROP TABLE IF EXISTS foo;
+
+CREATE TABLE foo (
+  id   INTEGER      NOT NULL AUTO_INCREMENT,
+  title VARCHAR(250) NOT NULL,
+  body VARCHAR(250),
+  PRIMARY KEY (id)
+);

spring-boot-modules/spring-boot-springdoc/src/test/java/com/baeldung/restdocopenapi/restdoc/SpringRestDocsUnitTest.java

@@ -0,0 +1,120 @@
+package com.baeldung.restdocopenapi.restdoc;
+
+import static org.hamcrest.Matchers.containsString;
+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.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.request.RequestDocumentation.parameterWithName;
+import static org.springframework.restdocs.request.RequestDocumentation.pathParameters;
+import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
+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 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.restdocopenapi.Application;
+import com.baeldung.restdocopenapi.Foo;
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+@ExtendWith({ RestDocumentationExtension.class, SpringExtension.class })
+@SpringBootTest(classes = Application.class)
+public class SpringRestDocsUnitTest {
+
+    private MockMvc mockMvc;
+    
+    @Autowired
+    private ObjectMapper objectMapper;
+
+    @BeforeEach
+    public void setup(WebApplicationContext webApplicationContext, RestDocumentationContextProvider restDocumentation) {
+        this.mockMvc = MockMvcBuilders.webAppContextSetup(webApplicationContext)
+            .apply(documentationConfiguration(restDocumentation))
+            .build();
+    }
+
+    @Test
+    public void whenGetFoo_thenSuccessful() throws Exception {
+        this.mockMvc.perform(get("/foo"))
+            .andDo(print())
+            .andExpect(status().isOk())
+            .andExpect(content().string(containsString("Foo 1")))
+            .andDo(document("getAllFoos"));
+    }
+
+    @Test
+    public void whenGetFooById_thenSuccessful() throws Exception {
+        ConstraintDescriptions desc = new ConstraintDescriptions(Foo.class);
+
+        this.mockMvc.perform(get("/foo/{id}", 1))
+            .andExpect(status().isOk())
+            .andDo(document("getAFoo", preprocessRequest(prettyPrint()), preprocessResponse(prettyPrint()), 
+                pathParameters(parameterWithName("id").description("id of foo to be searched")),
+                responseFields(fieldWithPath("id").description("The id of the foo" + collectionToDelimitedString(desc.descriptionsForProperty("id"), ". ")),
+                fieldWithPath("title").description("The title of the foo"), fieldWithPath("body").description("The body of the foo"))));
+    }
+
+    @Test
+    public void whenPostFoo_thenSuccessful() throws Exception {
+        Map<String, Object> foo = new HashMap<>();
+        foo.put("id", 4L);
+        foo.put("title", "New Foo");
+        foo.put("body", "Body of New Foo");
+    
+        this.mockMvc.perform(post("/foo").contentType(MediaTypes.HAL_JSON)
+            .content(this.objectMapper.writeValueAsString(foo)))
+            .andExpect(status().isCreated())
+            .andDo(document("createFoo", preprocessRequest(prettyPrint()), preprocessResponse(prettyPrint()), requestFields(fieldWithPath("id").description("The id of the foo"), fieldWithPath("title").description("The title of the foo"),
+                fieldWithPath("body").description("The body of the foo"))));
+    }
+    
+    @Test
+    public void whenDeleteFoo_thenSuccessful() throws Exception {
+        this.mockMvc.perform(delete("/foo/{id}", 2))
+            .andExpect(status().isNoContent())
+            .andDo(document("deleteFoo", pathParameters(parameterWithName("id").description("The id of the foo to delete"))));
+    }
+    
+    @Test
+    public void whenUpdateFoo_thenSuccessful() throws Exception {
+        
+        ConstraintDescriptions desc = new ConstraintDescriptions(Foo.class);
+    
+        Map<String, Object> foo = new HashMap<>();
+        foo.put("title", "Updated Foo");
+        foo.put("body", "Body of Updated Foo");
+    
+        this.mockMvc.perform(put("/foo/{id}", 3).contentType(MediaTypes.HAL_JSON)
+            .content(this.objectMapper.writeValueAsString(foo)))
+            .andExpect(status().isOk())
+            .andDo(document("updateFoo", pathParameters(parameterWithName("id").description("The id of the foo to update")),
+                responseFields(fieldWithPath("id").description("The id of the updated foo" + collectionToDelimitedString(desc.descriptionsForProperty("id"), ". ")),
+                    fieldWithPath("title").description("The title of the updated foo"), fieldWithPath("body").description("The body of the updated foo"))));
+    }
+    
+
+}