Forem: Francisco Pereira

Creating a REST API using Spring Boot + Tests + Documentation [part 05]

Francisco Pereira — Wed, 01 Feb 2023 18:16:34 +0000

Hello!

I'm back in this tutorial to teach you how to develop a REST API using Spring Boot. As I said earlier, this tutorial is divided into 5 parts as shown in the following table:

Part	Content
Part 01	Application Startup
Part 02	Settings and Database
Part 03	API Implementation
Part 04	Tests + Coverage
Part 05	Swagger Documentation

It is expected that from this final part you will learn the following:

Use of Swagger for project documentation.

Remembering that in this tutorial the following tools are used:

JDK 17
IntelliJ
Insomnia
Maven
MySQL database

We arrived at our last part of the tutorial. In the previous part you learned how to do unit and integration tests. In addition to also checking the coverage of tests performed.

In this last part, which will be a little shorter, you'll learn how to document your API.

When we work with an API we have to keep in mind that other developers will want access to it. Not necessarily to your source code, but to the responses from requests.

Therefore, we need to create documentation that will visually present all possible access routes of our system and their responses.

Step 01 - Added the SpringDoc library

We will be using Swagger which is already well known for documenting APIs

To use it within our application, we will have to add the Spring Doc dependency within the pom.xml file:


<dependency>
   <groupId>org.springdoc</groupId>
   <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
   <version>2.0.2</version>
</dependency>

By doing this (and restarting your server), we can access the URL http://localhost:8080/swagger-ui/index.html and the following screen will be seen:

As you can see, Swagger already mapped all the routes we created in the system, but it didn't complete all the necessary information for a good documentation. For example, clicking to see more information about the following route:

It only shows that the response will be a String, instead of showing the actual content. Therefore, we will have to make the following modification to our controller:


package com.simplelibrary.simplelibraryAPI.controller;

import com.simplelibrary.simplelibraryAPI.dto.BookRequestDTO;
import com.simplelibrary.simplelibraryAPI.dto.BookResponseDTO;
import com.simplelibrary.simplelibraryAPI.model.Book;
import com.simplelibrary.simplelibraryAPI.service.BookService;
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 jakarta.validation.Valid;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.web.PageableDefault;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.util.UriComponentsBuilder;

import java.io.IOException;

@RestController
@RequestMapping("books")
public class BookController {

@Autowired
private BookService bookService;


@ApiResponse(
            content = { @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = BookResponseDTO.class)))})
@GetMapping
public ResponseEntity<Page<BookResponseDTO>> getAllBooks(@PageableDefault(size=10, sort={"title"}) Pageable pagination) throws IOException {
    var page = bookService.getAllBooks(pagination);
    return ResponseEntity.ok(page);
}

    @ApiResponse(
            content = { @Content(mediaType = "application/json", schema = @Schema(implementation = BookResponseDTO.class))})

@GetMapping("/{id}")
public ResponseEntity show(@PathVariable Long id){
    var book = bookService.show(id);
    return ResponseEntity.ok(book);
}


@ApiResponse(
            content = { @Content(mediaType = "application/json", schema = @Schema(implementation = Book.class))})
@PostMapping
    public ResponseEntity store(@RequestBody @Valid BookRequestDTO bookRequest, UriComponentsBuilder uriBuilder) throws IOException {
        var book = bookService.store(bookRequest);
        var uri = uriBuilder.path("/books/{id}").buildAndExpand(book.getId()).toUri();
        return ResponseEntity.created(uri).body(book);
    }

@ApiResponse(
            content = { @Content(mediaType = "application/json", schema = @Schema(implementation = Book.class))})
@PutMapping("/{id}")
    public ResponseEntity update(@PathVariable Long id, @RequestBody @Valid BookRequestDTO bookRequest){
    var book = bookService.update(id, bookRequest);
    return ResponseEntity.ok(book);

}

@DeleteMapping("/{id}")
    public ResponseEntity delete(@PathVariable Long id){
    bookService.delete(id);
    return ResponseEntity.noContent().build();
}




}

Note that the @ApiResponse annotation has been added. Inside it, we put what will be the response content of each route. So, when checking the same route:

You can, if you want, create requests from this screen by clicking on the Try it out button:

What we learned in this tutorial

Well folks, I hope you enjoyed this sequel of the Spring Boot tutorial. I believe that with the knowledge gained from these 5 parts, you can start moving towards creating more robust applications.

Don't stick to just what was taught in this tutorial, be free to modify any piece of code that was added here. Any questions you can contact me!

Remembering once again, the complete project you can find HERE

Creating a REST API using Spring Boot + Tests + Documentation [part 04]

Francisco Pereira — Wed, 01 Feb 2023 18:16:33 +0000

Hello!

I'm back in this tutorial to teach you how to develop a REST API using Spring Boot. As I said earlier, this tutorial is divided into 5 parts as shown in the following table:

Part	Content
Part 01	Application Startup
Part 02	Settings and Database
Part 03	API Implementation
Part 04	Tests + Coverage
Part 05	Swagger Documentation

It is expected that from this fourth part you will learn the following:

Use of Junit
Creation of Unit Tests
Creation of Integration Tests
Using Fakers to create test data

Remember that in this tutorial the following tools are used:

JDK 17
IntelliJ
Maven
Insomnia
MySQL database

Step 01 - Creating test properties

Usually when we have to test our application, we create a properties file dedicated to the tests. This is done to have a better organization of development and test environments.
So, inside resources you can create a new file called application-test.properties which will contain the following content:


spring.datasource.url=jdbc:mysql://localhost:3307/small_library_test
spring.datasource.username=root
spring.datasource.password=root
spring.jpa.properties.hibernate.enable_lazy_load_no_trans=true

The first three items are responsible of the database connection. Note that a new database (small_library_test) has been created for the tests but if you want, you can use the same database used for development.
The last item is present to avoid the LazyInitializationException exception.

Therefore, when we create our tests, they will be using the properties defined in this new file.

Step 02 - Exception Handlers

By default, Spring handles some exceptions through classes, such as EntityNotFoundException and EmptyResultDataAccessException.

The first case happens when the user tries to search for an object in the database that does not exist, for example they would like to find a book whose id is equal to 9999999999 (thinking about the case in which this id does not exist in the database). By default, it returns error 500 (bad request) along with the exception body.

But let's think that in this case instead of returning the error 500, we would like to return the error 404 (Not Found). How can we carry out this modification?

That's why there is the RestControllerAdvice, it is used for handling exceptions in controllers. For its creation, you'll have to go to the src.main.java.com.simplelibrary.simplelibrary.API package and create a new package called exception. And inside this, create a class called ErrorHandler:


package com.simplelibrary.simplelibraryAPI.exception;

import jakarta.persistence.EntityNotFoundException;
import org.springframework.dao.EmptyResultDataAccessException;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import com.simplelibrary.simplelibraryAPI.dto.ErrorValidatorDTO;

@RestControllerAdvice
public class ErrorHandler {
    @ExceptionHandler({EntityNotFoundException.class, EmptyResultDataAccessException.class})
    public ResponseEntity error404(){
        return ResponseEntity.notFound().build();
    }


    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity error400(MethodArgumentNotValidException exception){
        var erros = exception.getFieldErrors();
        return ResponseEntity.badRequest().body(erros.stream().map(ErrorValidatorDTO::new).toList());
    }



}

In order for Spring to recognize that class as a Rest Controller Advice, you must place the @RestControllerAdvice annotation before the class initialization.

For each exception you want to handle, you must put it inside the @ExceptionHandler annotation saying that that exception will be handled inside the next method.
Note that the error404 method will handle exceptions that normally throw the 500 error and cause them to throw the 404 error.

The error400 method will handle the exception MethodArgumentNotValidException. This exception is triggered when there is a validation error, for example, when the user tries to register a book without its title. Originally, the response he will receive is as follows:


{
    "timestamp": "2023-01-27T19:04:03.372+00:00",
    "status": 400,
    "error": "Bad Request",
    "trace": "org.springframework.web.bind.MethodArgumentNotValidException: Validation failed for argument [0] in public org.springframework.http.ResponseEntity com.simplelibrary.simplelibraryAPI.controller.BookController.store(com.simplelibrary.simplelibraryAPI.dto.BookRequestDTO,org.springframework.web.util.UriComponentsBuilder) throws java.io.IOException: [Field error in object 'bookRequestDTO' on field 'title': rejected value [null]; codes [NotBlank.bookRequestDTO.title,NotBlank.title,NotBlank.java.lang.String,NotBlank]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [bookRequestDTO.title,title]; arguments []; default message [title]]; default message [não deve estar em branco]] \r\n\tat org.springframework.web.servlet.mvc.method.annotation.RequestResponseBodyMethodProcessor.resolveArgument(RequestResponseBodyMethodProcessor.java:144)\r\n\tat org.springframework.web.method.support.HandlerMethodArgumentResolverComposite.resolveArgument(HandlerMethodArgumentResolverComposite.java:122)\r\n\tat org.springframework.web.method.support.InvocableHandlerMethod.getMethodArgumentValues(InvocableHandlerMethod.java:181)\r\n\tat org.springframework.web.method.support.InvocableHandlerMethod.invokeForRequest(InvocableHandlerMethod.java:148)\r\n\tat org.springframework.web.servlet.mvc.method.annotation.ServletInvocableHandlerMethod.invokeAndHandle(ServletInvocableHandlerMethod.java:117)\r\n\tat org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter.invokeHandlerMethod(RequestMappingHandlerAdapter.java:884)\r\n\tat org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter.handleInternal(RequestMappingHandlerAdapter.java:797)\r\n\tat org.springframework.web.servlet.mvc.method.AbstractHandlerMethodAdapter.handle(AbstractHandlerMethodAdapter.java:87)\r\n\tat org.springframework.web.servlet.DispatcherServlet.doDispatch(DispatcherServlet.java:1080)\r\n\tat org.springframework.web.servlet.DispatcherServlet.doService(DispatcherServlet.java:973)\r\n\tat org.springframework.web.servlet.FrameworkServlet.processRequest(FrameworkServlet.java:1010)\r\n\tat org.springframework.web.servlet.FrameworkServlet.doPost(FrameworkServlet.java:913)\r\n\tat jakarta.servlet.http.HttpServlet.service(HttpServlet.java:731)\r\n\tat org.springframework.web.servlet.FrameworkServlet.service(FrameworkServlet.java:884)\r\n\tat jakarta.servlet.http.HttpServlet.service(HttpServlet.java:814)\r\n\tat org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:223)\r\n\tat org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:158)\r\n\tat org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:53)\r\n\tat org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:185)\r\n\tat org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:158)\r\n\tat org.springframework.web.filter.RequestContextFilter.doFilterInternal(RequestContextFilter.java:100)\r\n\tat org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:116)\r\n\tat org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:185)\r\n\tat org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:158)\r\n\tat org.springframework.web.filter.FormContentFilter.doFilterInternal(FormContentFilter.java:93)\r\n\tat org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:116)\r\n\tat org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:185)\r\n\tat org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:158)\r\n\tat org.springframework.web.filter.CharacterEncodingFilter.doFilterInternal(CharacterEncodingFilter.java:201)\r\n\tat org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:116)\r\n\tat org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:185)\r\n\tat org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:158)\r\n\tat org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:177)\r\n\tat org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:97)\r\n\tat org.apache.catalina.authenticator.AuthenticatorBase.invoke(AuthenticatorBase.java:542)\r\n\tat org.apache.catalina.core.StandardHostValve.invoke(StandardHostValve.java:119)\r\n\tat org.apache.catalina.valves.ErrorReportValve.invoke(ErrorReportValve.java:92)\r\n\tat org.apache.catalina.core.StandardEngineValve.invoke(StandardEngineValve.java:78)\r\n\tat org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:357)\r\n\tat org.apache.coyote.http11.Http11Processor.service(Http11Processor.java:400)\r\n\tat org.apache.coyote.AbstractProcessorLight.process(AbstractProcessorLight.java:65)\r\n\tat org.apache.coyote.AbstractProtocol$ConnectionHandler.process(AbstractProtocol.java:859)\r\n\tat org.apache.tomcat.util.net.NioEndpoint$SocketProcessor.doRun(NioEndpoint.java:1734)\r\n\tat org.apache.tomcat.util.net.SocketProcessorBase.run(SocketProcessorBase.java:52)\r\n\tat org.apache.tomcat.util.threads.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1191)\r\n\tat org.apache.tomcat.util.threads.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:659)\r\n\tat org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61)\r\n\tat java.base/java.lang.Thread.run(Thread.java:833)\r\n",
    "message": "Validation failed for object='bookRequestDTO'. Error count: 1",
    "errors": [
        {
            "codes": [
                "NotBlank.bookRequestDTO.title",
                "NotBlank.title",
                "NotBlank.java.lang.String",
                "NotBlank"
            ],
            "arguments": [
                {
                    "codes": [
                        "bookRequestDTO.title",
                        "title"
                    ],
                    "arguments": null,
                    "defaultMessage": "title",
                    "code": "title"
                }
            ],
            "defaultMessage": "must not be blank",
            "objectName": "bookRequestDTO",
            "field": "title",
            "rejectedValue": null,
            "bindingFailure": false,
            "code": "NotBlank"
        }
    ],
    "path": "/books"
}

Realize the amount of information that is sent to the user, when in fact we just want them to know which field is with the error and what the error message is. Therefore, we will carry out your treatment through a DTO.

Inside the src.main.java.com.simplelibrary.simplelibrary.API.dto package we will create a record called ErrorValidatorDTO:


package com.simplelibrary.simplelibraryAPI.dto;
import org.springframework.validation.FieldError;
public record ErrorValidatorDTO(String field, String message){
    public ErrorValidatorDTO(FieldError error){
        this(error.getField(), error.getDefaultMessage());
    }
}

From there we will get the error object and return to the user only the necessary information:


[
    {
        "field": "title",
        "message": "must not be blank"
    }
]

Step 03 - Book Factory

For our tests it will be necessary to create several books with different information. Carrying out this manual work is a bit exhausting, so we can use mechanisms created by the community.

One of the mechanisms we will use is Faker. From it, we will be able to generate random values for the fields and create our book object. For that, you'll need to import the following dependency into your pom.xml file:


<dependency>
   <groupId>com.github.javafaker</groupId>
   <artifactId>javafaker</artifactId>
   <version>1.0.2</version>
</dependency>

By doing this we can create the BookFactory class that will be responsible for creating book objects (DAO and DTO request models):

Inside the src.main.java.com.simplelibrary.simplelibrary.API.factory package we will create a class called BookFakerFactory:


package com.simplelibrary.simplelibraryAPI.factory;

import com.github.javafaker.Faker;
import com.simplelibrary.simplelibraryAPI.dto.BookRequestDTO;
import com.simplelibrary.simplelibraryAPI.model.Book;

public class BookFakerFactory {

    private Faker faker;

    public BookFakerFactory(){
        this.faker = new Faker();
    }

    public BookRequestDTO createBook(){
        var book = new BookRequestDTO(faker.book().title(), faker.book().author(),
                faker.number().randomDigit(), faker.number().digits(13), faker.number().randomDouble(1,1,10),
                faker.random().nextBoolean());

        return book;
    }

    public BookRequestDTO createBook(Book bookCreated){
        var book = new BookRequestDTO(bookCreated);
        return book;
    }

    public Book createBookModel(){
        var bookDTO = new BookRequestDTO(faker.book().title(), faker.book().author(),
                faker.number().randomDigit(), faker.number().digits(13), faker.number().randomDouble(1,1,10),
                faker.random().nextBoolean());

        var book = new Book(bookDTO);
        return book;
    }



    public BookRequestDTO createBookIncomplete(){
        var book = new BookRequestDTO(faker.book().title(), "",
                faker.number().randomDigit(), faker.number().digits(13), faker.number().randomDouble(1,1,10),
                faker.random().nextBoolean());

        return book;
    }

}

Note that we have 4 methods and the objective of all is to create an object that will later be used in tests.

The createBook method will create a BookRequestDTO object that will be used to test requests.
The createBook method (with parameter) will create a BookRequestDTO object from a previously created book.
The createBookModel method will create a Book object.
The createBookIncomplete method will create a BookRequestDTO object without author information.

Note that all methods use the Faker library.

Step 04 - Unit Tests

We are ready to create our tests. If you look inside the test package, there is already a class called SimplelibraryApiApplicationTests:


package com.simplelibrary.simplelibraryAPI;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;

@SpringBootTest
class SimplelibraryApiApplicationTests {


    @Test
    void contextLoads() throws Exception {


    }

}

It will use JUnit for testing.

Note some annotations that are important:

@SpringBootTest indicates that that class will contain methods that should be tested.
@Test indicates that that method should be run as a test.

So we can create our first unit test. This one will test some features of our repository: inside the src.main.test.java.com.simplelibrary.simplelibrary.API package we will create a package called unit and inside it a class called BookTest:


package com.simplelibrary.simplelibraryAPI.unit;

import com.simplelibrary.simplelibraryAPI.factory.BookFakerFactory;
import com.simplelibrary.simplelibraryAPI.repository.BookRepository;
import com.simplelibrary.simplelibraryAPI.service.BookService;
import org.assertj.core.api.Assertions;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.ActiveProfiles;
import static org.assertj.core.api.Assertions.*;
import java.io.IOException;

@SpringBootTest
@ActiveProfiles("test")
public class BookTest {

    @Autowired
    private BookRepository repository;

    @Autowired
    private BookService service;

    private BookFakerFactory bookFakerFactory;

    public BookTest() {
        this.bookFakerFactory = new BookFakerFactory();
    }



}

Notice the @ActiveProfiles("test") annotation. It is used to inform Spring that we are using the properties defined inside the application-test.properties file.

We can think of some tests to be done:

Test for successfully creating a book.
Test to verify if the service of collecting the rating of a given book is working correctly (verifying that the rating value is populated when it is from an existing book and that it is not populated with a non-existing book).

The class with all the tests looks like this:


package com.simplelibrary.simplelibraryAPI.unit;

import com.simplelibrary.simplelibraryAPI.factory.BookFakerFactory;
import com.simplelibrary.simplelibraryAPI.repository.BookRepository;
import com.simplelibrary.simplelibraryAPI.service.BookService;
import org.assertj.core.api.Assertions;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.ActiveProfiles;
import static org.assertj.core.api.Assertions.*;
import java.io.IOException;

@SpringBootTest
@ActiveProfiles("test")
public class BookTest {

    @Autowired
    private BookRepository repository;

    @Autowired
    private BookService service;

    private BookFakerFactory bookFakerFactory;

    public BookTest() {
        this.bookFakerFactory = new BookFakerFactory();
    }

    @Test
    public void itShouldCreateABookSuccessfully(){
        var book = bookFakerFactory.createBookModel();
        repository.save(book);

        var bookFinder = repository.findBookByisbn(book.getIsbn());

        Assertions.assertThat(book).isEqualTo(bookFinder);
    }

    @Test
    public void itShouldFillTheRatingValueFromExistingBook() throws IOException {
        var book = bookFakerFactory.createBookModel();
        book.setTitle("Harry Potter and the Philosopher's Stone");

        var bookCreated = service.store(bookFakerFactory.createBook(book));

        assertThat(bookCreated.getRate()).isNotNull()
                .isNotZero()
                .isGreaterThan(Double.valueOf(0));

    }

    @Test
    public void itShouldNotFillTheRatingValueFromNonexistentBook() throws IOException {
        var book = bookFakerFactory.createBookModel();
        book.setTitle("blablablablablabla");

        var bookCreated = service.store(bookFakerFactory.createBook(book));

        assertThat(bookCreated.getRate()).isZero();

    }



}

Note the use of the assertThat method present in JUnit, which allows checking values.

Step 05 - Integration tests

We can now create the integration test that will allow us to test our system's routes. We will also check if the requests are returned correctly and if the http codes also match expectations.

Inside the src.main.test.java.com.simplelibrary.simplelibrary.API package we will create a package called integration and inside it a class called BookControllerTest:


package com.simplelibrary.simplelibraryAPI.integration;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.simplelibrary.simplelibraryAPI.factory.BookFakerFactory;
import com.simplelibrary.simplelibraryAPI.repository.BookRepository;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.test.context.ActiveProfiles;
import org.springframework.test.web.servlet.MockMvc;

import static org.junit.jupiter.api.Assertions.assertNotNull;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import static org.assertj.core.api.Assertions.*;
@SpringBootTest
@AutoConfigureMockMvc
@ActiveProfiles("test")
public class BookControllerTest {

@Autowired
    private MockMvc mockMvc;

    @Autowired
    private BookRepository repository;

    private BookFakerFactory bookFakerFactory;

    public BookControllerTest() {
        this.bookFakerFactory = new BookFakerFactory();
    }


}

Note the use of a new annotation: @AutoConfigureMockMvc from it we will be able to use the injected MockMvc class to make requests to our server.

We can think of the following test cases:

Verification if a book is successfully created
Verification if a book is not created when we don't send all the necessary fields (http code 400)
Verification if all books are successfully listed
Verification if the information of a single book appears successfully.
Verification if a book's information is changed successfully
Verification that a book's information is not successfully changed when its information is not submitted.
Verification if a book is successfully deleted.
Verification that a non-existent book is not deleted.

The class with all implemented methods looks like this:


package com.simplelibrary.simplelibraryAPI.integration;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.simplelibrary.simplelibraryAPI.factory.BookFakerFactory;
import com.simplelibrary.simplelibraryAPI.repository.BookRepository;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.test.context.ActiveProfiles;
import org.springframework.test.web.servlet.MockMvc;

import static org.junit.jupiter.api.Assertions.assertNotNull;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import static org.assertj.core.api.Assertions.*;
@SpringBootTest
@AutoConfigureMockMvc
@ActiveProfiles("test")
public class BookControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Autowired
    private BookRepository repository;

    private BookFakerFactory bookFakerFactory;

    public BookControllerTest() {
        this.bookFakerFactory = new BookFakerFactory();
    }

    @Test
    void testIfBookIsCreatedSuccessfully() throws Exception {
        var book = this.bookFakerFactory.createBook();

        var result = this.mockMvc.perform(post("/books")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content(asJsonString(book)))
                .andExpect(status().isCreated())
                .andReturn();

        String content = result.getResponse().getContentAsString();
        assertNotNull(content);

    }

    @Test
    void testIfBookIsNotCreatedWithMissingAttributes() throws Exception{
        var book = this.bookFakerFactory.createBookIncomplete();
        this.mockMvc.perform(post("/books")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content(asJsonString(book)))
                .andExpect(status().isBadRequest())
                .andReturn();

    }

    @Test
    void testIfAllBooksAreListedSuccessfully() throws Exception{
        this.mockMvc.perform(get("/books"))
                .andExpect(status().isOk())
                .andReturn();
    }

    @Test
    void testIfSingleBookInformationIsShown() throws  Exception {
        this.mockMvc.perform(get("/books"))
                .andExpect(status().isOk())
                .andReturn();
    }

    @Test
    void testIfBookIsUpdatedSuccessfully() throws Exception{
        var book = this.bookFakerFactory.createBookModel();
        var bookCreated = repository.save(book);

        book.setAuthor("New Author name");

        var book2 = this.bookFakerFactory.createBook(book);

        this.mockMvc.perform(put("/books/{id}",bookCreated.getId())
                        .contentType(MediaType.APPLICATION_JSON)
                        .content(asJsonString(book2)))
                .andExpect(status().isOk())
                .andReturn();

        var bookUpdated = repository.getReferenceById(bookCreated.getId());

        assertThat(bookUpdated.getId()).isEqualTo(bookCreated.getId());
        assertThat(bookUpdated.getAuthor()).isNotEqualTo(bookCreated.getAuthor());


    }

    @Test
    void testIfBookIsNotUpdatedSuccessfully() throws Exception{
        var book = this.bookFakerFactory.createBookModel();
        var bookCreated = repository.save(book);


        this.mockMvc.perform(put("/books/{id}",bookCreated.getId()))
                .andExpect(status().isBadRequest())
                .andReturn();


    }

    @Test
    void testIfBookIsDeletedSuccessfully() throws Exception{
        var book = this.bookFakerFactory.createBookModel();
        var bookCreated = repository.save(book);
        this.mockMvc.perform(delete("/books/"+bookCreated.getId()))
                .andExpect(status().isNoContent())
                .andReturn();
    }

    @Test
    void testIfBookIsNotDeletedSuccessfully() throws Exception{
        this.mockMvc.perform(delete("/books/999999"))
                .andExpect(status().isNotFound())
                .andReturn();

    }

    public static String asJsonString(final Object obj) {
        try {
            return new ObjectMapper().writeValueAsString(obj);
        } catch (Exception e) {
            throw new RuntimeException(e);
        }


    }
}

Note the use of the asJsonString method. It is used to take all the attribute values of an object and transform it into a Json string.

Step 06 - Running the tests

To run the tests you will have to go to the terminal and type the following command:


\.mvnw test

By doing this you will inform maven that you want to run all the tests in your application:

If all tests run successfully, you will see the following:

Step 07 - Test Coverage

Finally, many times when we do tests we would like to understand how broad it was. We would like to reach as many classes and methods as possible in our project, thus avoiding letting any part go unnoticed.

We can use the JaCoCo plugin to check test coverage. Its documentation is present at this link.

To use it, you'll need to go to your pom.xml file and add the following plugin:


<plugin>
   <groupId>org.jacoco</groupId>
   <artifactId>jacoco-maven-plugin</artifactId>
   <version>0.8.8</version>
   <executions>
      <execution>
         <goals>
            <goal>prepare-agent</goal>
         </goals>
      </execution>
      <execution>
         <id>report</id>
         <phase>test</phase>
         <goals>
            <goal>report</goal>
         </goals>
      </execution>
   </executions>
</plugin>

Just that! Now you can rerun your tests and when they are finished a .html file will be generated inside target.site.jacoco. The file is index.html and when accessing it you will have a screen similar to this one:

As you can see, the com.simplelibrary.simplelibraryAPI.model package had 70% of coverage. For more information, you can click on the package and then on the desired class to have the following coverage view:

Green means that the code snippet was called.

Therefore, you can use the plugin and add new tests so that the coverage value of a given class is as high as possible!

What we learned in this tutorial

In this third part, we learned how to perform unit and integration tests using JUnit. We also saw how we can check test coverage using the JaCoCo plugin.

In the next part you will see about project documentation using Swagger.

Remembering that the complete project can be found HERE

Creating a REST API using Spring Boot + Tests + Documentation [part 03]

Francisco Pereira — Wed, 01 Feb 2023 18:16:31 +0000

Hi!

I'm back in this tutorial to teach you how to develop a REST API using Spring Boot. As I said earlier, this tutorial is divided into 5 parts as shown in the following table:

Part	Content
Part 01	Application Startup
Part 02	Settings and Database
Part 03	API Implementation
Part 04	Tests + Coverage
Part 05	Swagger Documentation

It is expected that from this third part you will learn the following:

How to create a service containing the system's business rule
How to create the controllers containing the system's routes

Remember that in this tutorial the following tools are used:

JDK 17
IntelliJ
Maven
Insomnia
MySQL database

Step 01 - Creating the service

We created the Book class repository which will allow us to perform the necessary manipulations in the database (inserting, deleting, editing and viewing data, for example).

Now we can implement the system's business rule, this implementation can be done directly in Controller where we will have access routes to the system. But in doing so we are not following the Single Responsibility Principle. Therefore, Spring Boot indicates the creation of a service for the implementation of the business rule.

To create the service, we'll go into the src.main.java.com.simplelibrary.simplelibrary.API package and create a new package called service. And inside of this, we create an interface called BookService:

package com.simplelibrary.simplelibraryAPI.service;

import com.simplelibrary.simplelibraryAPI.dto.BookRequestDTO;
import com.simplelibrary.simplelibraryAPI.dto.BookResponseDTO;
import com.simplelibrary.simplelibraryAPI.model.Book;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;

import java.io.IOException;

public interface BookService {
    public Page<BookResponseDTO> getAllBooks(Pageable pagination);

    public BookResponseDTO show(Long id);

    public Book store(BookRequestDTO book) throws IOException;

    public BookResponseDTO update(Long id, BookRequestDTO book);

    public void delete(Long id);

    public long count();

}

The getAllBooks method will be used to get all the books in the database. It will receive as a parameter an object of type Pageable which is responsible for pagination. Later when we implement the route, we'll talk about this class. Finally, it will return an object of type Page that will contain the contents of the BookResponseDTO class.
The show method will be used to get the information of only 1 book. It will receive the id of this book as a parameter and return the BookResponseDTO.
The store method will be used to store a book in the database. It will receive the information from the BookRequestDTO and return the Book. In its implementation we will talk more about this return.
The update method will be used to update the book information. It will receive the id of the book and its information (BookRequestDTO) and will return the BookResponseDTO.
The delete method will be used to delete a book from the database. For this we only need your id.
The count method will be used to check how many books have been registered in the database. A long value will be returned.

After creating the interface, we can now create its implementation. For that, we'll go into the src.main.java.com.simplelibrary.simplelibrary.API.service package and create a new package called impl. And inside this, we create an interface called BookServiceImpl.

Initially the class will have the following format:

import org.springframework.stereotype.Service;
import com.simplelibrary.simplelibraryAPI.service.BookService;
import org.springframework.beans.factory.annotation.Autowired;

@Service
public class BookServiceImpl implements BookService {

@Autowired
    private BookRepository bookRepository;

}

As we are creating the implementation of a service, we need to insert the @Service annotation at the beginning of the class. By doing this, Spring will understand that this class is indeed a Service.

And notice the @Autowired annotation it is used for dependency injection. We want to inject the BookRepository to be used in your database manipulation methods. Therefore, we need to inform the @Autowired annotation before its declaration so that Spring can be taking care of this dependency.

Once this is done, we can implement the methods that belong to the interface we created earlier:

getAllBooks

@Override
public Page<BookResponseDTO> getAllBooks(Pageable pagination){
        var page = bookRepository.findAll(pagination).map(BookResponseDTO::new);
        return page;
    }

The repository has a method called findAll which will return all the books present in the database. It can receive a Pageable object as a parameter that will contain the paging information (trust me, we'll talk more about how this object is built later).

This result, by default, will return objects of type Book (DAO), because in the declaration of the repository we inform in the generics that it is of type Book. However, we previously defined that the return to the user has to be of type BookResponseDTO. Therefore, we will make a map to call the BookResponseDTO constructor that will receive data from an object of type Book and fill in its attributes.

Finally, we will return the result that has been found.

show


  @Override
    public BookResponseDTO show(Long id) {
        return new BookResponseDTO(bookRepository.getReferenceById(id));
    }

The show method is quite simple to understand.
We will use the getReferenceById method that will return a Book type object based on its id. Finally, we do the conversion to BookResponseDTO by calling its constructor.

store

@Override
    public Book store(BookRequestDTO bookRequest) throws IOException {
        var book = new Book(bookRequest);
        book.setRate(this.scrapRatings(book.getTitle()));
        bookRepository.save(book);
        return book;
    }

The store method is used to store a book in the database. Notice that in the first line, a Book object is created and passed in its constructor the bookRequest object. Therefore, you will create the constructor inside the Book class:


 public Book(BookRequestDTO bookRequest){
        this.title = bookRequest.title();
        this.author = bookRequest.author();
        this.pages = bookRequest.pages();
        this.isbn = bookRequest.isbn();
        this.rate = bookRequest.rate();
        this.finished = bookRequest.finished();
    }

Next, we make the logic for filling in the value of the book's rate. As presented in the system scenario, this attribute will be filled according to what is found on the site http://www.skoob.com.br.

To extract data from the web (web scraping) I am using the Jsoup library. You can go to your pom.xml file and import it:

<dependency>            
   <groupId>org.jsoup</groupId>
   <artifactId>jsoup</artifactId>
   <version>1.15.3</version>
</dependency>

The scrapRatings method will look like this:


private Double scrapRatings(String title) {
        Double rating = Double.valueOf(0);
        try{
            String titleEdited = title.replace(" ","-");
            Document doc = Jsoup.connect("https://www.skoob.com.br/"+titleEdited).get();
            Elements info = doc.select( "div#resultadoBusca")
                    .select("div.box_lista_busca_vertical")
                    .select("div.detalhes")
                    .select("a");
            Element firstBook = info.first();
            if(firstBook != null){
                Document book = Jsoup.connect("https://www.skoob.com.br/"+firstBook.attr("href")).get();
                Elements ratingElement = book.select("div#pg-livro-box-rating")
                        .select("span.rating");
                rating = Double.parseDouble(ratingElement.text());
            }
        }catch (Exception e){
        }
        finally {
            return rating;
        }
    }

I won't go into much detail about Jsoup, but basically it will access a web page and return its html content where we can get its data.
The scrapRatings method will search the desired site based on the book title. And will return your evaluation. If the book is not found, your evaluation will be reset to zero.

If you want to know more about the Jsoup, you can go to this link: https://jsoup.org

Going back to the book insert method, after getting the book rating value, we can call the save method of the repository. This method will perform data persistence. Finally, we return the book that was created.

update


@Override
    public BookResponseDTO update(Long id, BookRequestDTO bookRequest) {
        var book = bookRepository.getReferenceById(id);
        book.update(bookRequest);
        return new BookResponseDTO(book);


    }

The update method will look for a book based on its id (using the getReferenceById method) and based on the data sent by the user, it will update them inside the Book object. So let's go back to the Book class and add the update method:

 public void update(BookRequestDTO bookRequest){
        this.title = bookRequest.title();
        this.author = bookRequest.author();
        this.pages = bookRequest.pages();
        this.isbn = bookRequest.isbn();
        this.rate = bookRequest.rate();
        this.finished = bookRequest.finished();
    }

Finally, we return the response DTO.

delete


@Override
    public void delete(Long id) {
        bookRepository.deleteById(id);
    }

The delete method will only call the deleteById method that belongs to the book repository. In this method we don't need to return anything.

count

@Override
public long count(){
        return bookRepository.count();
    }

The count method will return the count method which belongs to the book's repository.

Well done! We finalized the implementation of the business rule from the repository. We can go to the last step which is creating the routes that will call the repository!

Step 02 - Implementing the Route Controller

We arrived at the last step of creating our API. So far we have created our DAO class and the DTO records. The first one will serve as a base for the repository to carry out manipulations in the database. The second one will be used for data input and output.

In addition, we also created the Service that will contain the implementation of our system's business rule.

Now we can create the route controller.

Just like we did earlier in creating a controller to present a simple message to the user when accessing a route, we'll create a robust controller.

Inside the controller package you will create a class called BookController which will have the following initial body:

import com.simplelibrary.simplelibraryAPI.service.BookService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("books")
public class BookController {

@Autowired
private BookService bookService;


}

This time we are injecting the BookService so we can use the methods we created earlier. If you noticed, we are importing the interface we created and not the implementation. But don't worry, Spring will automatically recognize the implementation we made from the interface.

We have to create the following routes:

HTTP Method	/
GET	books
GET	/books/{id}
POST	/books
PUT	/books/{id}
DELETE	/books/{id}

Route to get all books:

@GetMapping
public ResponseEntity<Page<BookResponseDTO>> getAllBooks(@PageableDefault(size=10, sort={"title"}) Pageable pagination) throws IOException {
    var page = bookService.getAllBooks(pagination);
    return ResponseEntity.ok(page);
}

The route to get all the books will be accessed through a GET request on the URL http://localhost:8080/books. When performing the request, the getAllBooks method will be called.

Note that in the method's signature we are adding an object of type Pageable called pagination in the parameter. Associated with it there is the signature @PageableDefault(size=10, sort={"title"}), this object will allow us to define the pagination properties of my result (we passed this object inside the Service, remember?).

We are injecting the Pageable inside our method, we don't need to worry about creating your object or anything, Spring will do it for you! As per the project requirements we have the following:

As a user, I would like to get all the books registered in the system through pagination. Having only 10 books per page and sorting by title.

We are placing inside the annotation the size properties in which we specify how many books we want to be displayed per page. And the sort property which specifies what the ordering criteria will be, in this case it is title.

We will call the getAllBooks method of the Service we implemented and finally we return the ResponseEntity with the http code response 200, and the pagination in its body.

Route to get the information of a single book:

@GetMapping("/{id}")
public ResponseEntity show(@PathVariable Long id){
    var book = bookService.show(id);
    return ResponseEntity.ok(book);
}

The route to get the information of a single book will be accessed through a GET request on the URL http://localhost:8080/books/{id}. When performing the request, the show method will be called.

Note that for us to know which book the user would like to see the information, they need to specify the id. Therefore, the value of their id is passed in the URL. For this value to be recognized, we put the @PathVariable annotation in the parameters of the method and then its type and the variable where its value will be stored.

We will call the show method of the service and return the ResponseEntity with the http code 200.

Route to store a book


@PostMapping
    public ResponseEntity store(@RequestBody @Valid BookRequestDTO bookRequest, UriComponentsBuilder uriBuilder) throws IOException {
        var book = bookService.store(bookRequest);
        var uri = uriBuilder.path("/books/{id}").buildAndExpand(book.getId()).toUri();
        return ResponseEntity.created(uri).body(book);
    }

The path to store a book will be accessed via a POST request to the URL http://localhost:8080/books/. When performing the request, the store method will be called.

In this method, the user will send in the body of the request (@RequestBody) the fields that we inform in the BookRequestDTO record and where we put all the validations. For these validations to be "called" we need to put the @Valid annotation.
We are also injecting the UriComponentsBuilder into the parameters, which will be used in the response return.

If all validations are successful, the store method of the Service will be called and the book object will be returned.
It is a good API practice, when storing an object in the database, to add a URL to the response headers where the user can access to obtain information about the object that was created. This URL is obtained from the following snippet:


var uri = uriBuilder.path("/books/{id}").buildAndExpand(book.getId()).toUri();

Finally, it is also a good practice to fully return the object that was created in the request body. Therefore, we will not return a DTO object, but a Book type object. In addition to returning status 201 (created).

Route to update a book


@PutMapping("/{id}")
    public ResponseEntity update(@PathVariable Long id, @RequestBody @Valid BookRequestDTO bookRequest){
    var book = bookService.update(id, bookRequest);
    return ResponseEntity.ok(book);

}

The route to update a book will be accessed through a PUT request in the URL http://localhost:8080/books/id. When performing the request, the update method will be called.

This method is similar to the store method, only this time the user has to pass the book's id in the URL.

After calling the update method of the service, we will return the updated book with http status 200.

Route to delete a book

@DeleteMapping("/{id}")
    public ResponseEntity delete(@PathVariable Long id){
    bookService.delete(id);
    return ResponseEntity.noContent().build();
}

The route to delete a book will be accessed through a DELETE request in the URL http://localhost:8080/books/id. When performing the request, the delete method will be called.

This method only receives the id of the book and later the delete method of the service will be called where the book will be successfully deleted.

In this case, we are returning http code 204 (no content).

What we learned in this tutorial

Well done! We have finished creating our Rest API using Spring Boot. You can use Insomnia to test the requests and see if everything is working as expected.

In the next part of the tutorial, you will learn how to create unit and integration tests on your application!

You can find the full project HERE

Creating a REST API using Spring Boot + Tests + Documentation [part 02]

Francisco Pereira — Wed, 01 Feb 2023 18:16:29 +0000

Hi!

I'm back in this tutorial to teach you how to develop a REST API using Spring Boot. As I said earlier, this tutorial is divided into 5 parts as shown in the following table:

Part	Content
Part 01	Application Startup
Part 02	Settings and Database
Part 03	API Implementation
Part 04	Tests + Coverage
Part 05	Swagger Documentation

It is expected that from this second part you will learn the following:

How to create the system routes
How to view the system through user stories
How to view the system through ER diagram
How to create the database
How to integrate the database with the system
How to create migrations using flyway
How to create DAO classes
How to create a repository to interact with the database
How to create DTO records

Remember that in this tutorial the following tools are used:

JDK 17
IntelliJ
Maven
Insomnia
MySQL database

Step 01 - Creating routes

In the first part of the tutorial we created the project using Spring Initializr and ran the server. It turns out that when accessing the URL http://localhost:8080 we come across the following response:


{
    "timestamp": "2023-01-31T18:08:42.607+00:00",
    "status": 404,
    "error": "Not Found",
    "message": "No message available",
    "path": "/"
}

This response, as shown earlier, appears because we have not defined any route for our application.

So let's create our route!

Inside the src.main.java.com.simplelibrary.simplelibrary.API package we will create a new package called controller. Inside it, we will store the Controllers of the system.

Inside a controller we will have the mapping of our application's routes. Thus, when defining a route, such as "/test", when the user accesses the url http://localhost:8080/test, he will no longer find the response seen above.

The class that we will create in this controller will have the following code:

package com.simplelibrary.simplelibraryAPI.controller;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("test")
public class SimpleRouteController {

    @GetMapping
    public ResponseEntity test(){
        return ResponseEntity.ok("it works!");
    }
}

In the first lines we see some imports that are necessary for the project. Also note that some annotations are used, such as @RequestController.

According to Spring's own documentation, this annotation means that:

[...] Marks the class as a controller where every method returns a domain object instead of a view.

The next annotation, RequestMapping("test") indicates that all requests that have the /test mapping will be handled in this class.

The @GetMapping annotation indicates that the method below it will handle a get type request. That is, if the user accesses the URL http://localhost:8080/test (using the HTTP GET method), the method below will be called. The method itself is test:

@GetMapping
    public ResponseEntity test(){
        return ResponseEntity.ok("it works!");
    }

If you want to know more about HTTP methods, you can visit these links: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods, https://www.w3schools.com/tags/ref_httpmethods.asp

As shown, the method returns an object of type ResponseEntity. This class represents an HTTP return, where we can also insert the return codes (2xx, 4xx, 5xx...).

If you want to know more about HTTP response codes, you can visit this link: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

The ResponseEntity class already carries the possible HTTP response codes. In our case we are using the return ok which is indicated by the code 200. From this return, you can insert a body containing a message. In this case we are returning it works!".

Now when performing a GET request for the URL http://localhost:8080/test we get the following response:

Step 02 - User stories

Now that we know how to create a route, we can now see our system's scenarios from the user's point of view.

As a user, I would like to register books in the system by registering the following information: id, title, author, number of pages, isbn, evaluation, status (finished or not). I would also like that the evaluation of the book should be obtained automatically from the page of this book on the site http://skoob.com.br.

As a user, I would like to get all the books registered in the system through pagination. Having only 10 books per page and sorting by title.

As a user, I would like to obtain information of only one book, identified by its id.

As a user, I would like to update the information of a book, identified by its id.

As a user, I would like to delete a book based on its id.

Step 03 - System modeling

From the specifications presented above, we can model our system:

As you can see from the entity-relationship diagram, we will only have a single table in the database called Book and it will contain the following columns:

id (primary key)
title
author
pages
isbn (unique)
rate (nullable)
finished

Only the rate column can have a null value.

Step 04 - Creating the database

In this tutorial I will not be focusing on installing the database on your machine. On my machine I'm using a Docker container that contains the MySQL database.

Our database will be called small_library. So, to create the database you can run the following command in SQL:


create database small_library;
use small_library;

By doing this, your database will be created and ready for use in the application.

Step 05 - Integration of the database with the system

Once your database is ready, we can add some dependencies to the project that will help us connect the system to the database and perform some manipulations. Therefore, in your pom.xml file you can add the following dependencies between the <dependencies> and </dependencies> tags:

<!-- ... -->

<dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-data-jpa</artifactId>
   </dependency>
   <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-validation</artifactId>
   </dependency>
   <dependency>
      <groupId>org.flywaydb</groupId>
      <artifactId>flyway-core</artifactId>
   </dependency>
   <dependency>
      <groupId>org.flywaydb</groupId>
      <artifactId>flyway-mysql</artifactId>
   </dependency>
   <dependency>
      <groupId>com.mysql</groupId>
      <artifactId>mysql-connector-j</artifactId>
      <scope>runtime</scope>
   </dependency>

<!-- ... -->

The following dependencies are being added:

Flyway Migration: from it, we can create migrations for the database.
MySQL Driver: is the driver that will allow the connection between our server and the MySQL database
Spring Data JPA: from it we can persist data in the database from entities.
Validation: it is the validation service that we will use to verify that the data arriving at the server is in accordance with the established validation rules.

After that, you can reload the Maven dependencies. When running your application, the terminal will display the following message:

This message means that you have added the database dependencies on the system but have not added any connection properties. That is, Spring is trying to fetch the connection URL, the username and password to connect, but it is not finding it.

To change that, I recommend you close the server, and go to the application.properties file inside resources and add the following:

spring.datasource.url=jdbc:mysql://localhost:3307/small_library
spring.datasource.username=root
spring.datasource.password=root

In the spring.datasource.url tag, we inform you the URL to access your database. In my case, I'm using the mysql database and it's running on port 3307.

Finally, in the spring.datasource.username and spring.datasource.password tags we inform the database user name and password, respectively. In my case, I fill both with root.

By doing this we can start the server again and it will run successfully

Step 06 - Creating migrations

Now that we have successfully connected to the database, we can now create the scripts to create our books table. For the versioning of these scripts, we will be using the migrations system that is provided from the flyway dependency.

For those who don't know, a migration is a versioned sql script that allows you to add or modify a table in the database. This versioning is important to have a control of the modifications that are made in the database.

Flyway documentation can be found at this link here.

In Spring Boot, migrations are inside the resources.db.migration folder and each script must be saved with the following name:

<Prefix><Version>__<Description>.sql

Usually in the prefix we insert the letter V, meaning version.
In the version, we insert the version number, starting with 1 (and it will be incremented with each new script).
And in the description we insert what we are doing in that script.

We can create the following migration:

V1__create-table-books.sql

And inside of it the following script:


create table books(
      id bigint not null auto_increment,
      title varchar(100) not null,
      author varchar(100) not null,
      pages int not null,
      isbn varchar(100) not null unique,
      finished tinyint not null,
      rate float,

      primary key(id)
);

NOTE: It is highly recommended that you stop the server before creating a migration to avoid any problems.

When creating the migration, we can start the server and it will automatically run the migration, creating the table in the database:

Note that in addition to the books table, the flyway_schema_history table was also created. This table will store all migrations that have already been run and what is the current version of the system.

Step 07 - Creating the DAO class

So far we have made all the necessary configurations in the database. We can now create our DAO class that will help us access the data in the database.

Therefore, inside the src.main.java.com.simplelibrary.simplelibrary.API package we will create a new package called model. And inside this, we create a class called Book:

package com.simplelibrary.simplelibraryAPI.model;
import jakarta.persistence.*;
import lombok.*;
@Table(name = "books")
@Entity(name = "Book")
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@EqualsAndHashCode(of = "id")
public class Book {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String title;
    private String author;
    private Integer pages;
    private String isbn;
    private Double rate;
    private Boolean finished;

}

At first, the amount of Annotations can be daunting, but it is very easy to understand:

@Table(name = "books") refers to the table in the database that this class references. As we created the books table, we put this value.
@Entity(name = "Book") refers to the name of the DAO class - telling the Spring that it is an entity.
@Getter is a lombok annotation to generate getters methods for all attributes of the class.
@setter is a lombok annotation to generate the setters methods of all attributes of the class.
@NoArgsConstructor is a lombok annotation to generate the class constructor method with no arguments: public Book();
@AllArgsConstructor is a lombok annotation to generate the constructor method of the class with all the attributes of the class present in the arguments: public Book(Long id, String title, String author, Integer pages, String isbn, Double rate, Boolean finished );
@EqualsAndHashCode(of = "id") is a lombok annotation to generate equals method and hashCode generator using id as parameter.

Finally, we can also add what are the attributes of the class. We will use the columns present in the database as a reference.

Note: It is important to add the annotations @Id and @GeneratedValue(strategy = GenerationType.IDENTITY) before the declaration of the id attribute to inform that this attribute is an identifier.

Step 07 - Creating the repository

We previously created our DAO class. Now it is necessary to have a way to get the data from the database - this will be done through the repositories. A repository is an interface that inherits from the JpaRepository class. From it, we can perform manipulations on the database, considering a previously created DAO class.

To create the repository, we have to go inside the src.main.java.com.simplelibrary.simplelibrary.API package and create a new package called repository. And inside this, we create an interface called BookRepository:


package com.simplelibrary.simplelibraryAPI.repository;

import com.simplelibrary.simplelibraryAPI.model.Book;
import org.springframework.data.jpa.repository.JpaRepository;

public interface BookRepository extends JpaRepository<Book, Long> {

}

Only that! When doing the inheritance, we have to specify which entity it will use to get the data. In this case, it is the Book entity. We also have to specify what the type of the primary key is (in this case it is Long).

Step 08 - Thinking about input and output data

We are just a few steps away from finishing the implementation of our CRUD. Now is a good time to start thinking about how the data will arrive in our application and how we would like to return it to the user.

In previous steps, some system scenarios that we must implement were presented. One of them was the following:

As a user, I would like to register books in the system by registering the following information: id, title, author, number of pages, isbn, evaluation, status (finished or not). I would also like that the evaluation of the book should be obtained automatically from the page of this book on the site http://skoob.com.br.

We know that the identifier code (id) will be generated automatically by the system and that the evaluation of the book will be obtained through the website. Therefore, we expect that to register a book in the system, the user must inform the following fields:

Title
Author
Number of Pages
ISBN
Finished

Therefore, we can create a class that will be used for data transfer (DTO - Data Transfer Object). We'll go into the src.main.java.com.simplelibrary.simplelibrary.API package and create a new package called dto. And inside this, we create a record called BookRequestDTO:

package com.simplelibrary.simplelibraryAPI.dto;

import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;

public record BookRequestDTO(
        @NotBlank
        String title,
        @NotBlank
        String author,
        @NotNull
        Integer pages,
        @NotBlank
        String isbn,
        @NotNull
        Boolean finished
) {

}

For those who are not familiar, a record is an immutable type of class, that is, from the moment we create an object and fill in its data, these will not be changed. Your getters methods are created automatically.

Note that there are some annotations that were not explained earlier. As is the case with @NotBlank and @NotNull. These annotations are used for input validation. By default, we don't want any of our fields to be empty, so we add the @NotBlank annotation before Strings (which checks if the String is empty or null) and @NotNull before other classes.

When adding this validation, if the user fails to send a field, he will see a message informing the problem.

Alright, we made the record for the request, now we are going to make a new record for the response. That is, we will treat the data that will be sent to the user:


package com.simplelibrary.simplelibraryAPI.dto;

import com.simplelibrary.simplelibraryAPI.model.Book;

public record BookResponseDTO(String title, String author, Integer pages, String isbn, Double rate, Boolean finished) {
    public BookResponseDTO(Book book){
        this(book.getTitle(), book.getAuthor(), book.getPages(), book.getIsbn(), book.getRate(), book.getFinished());
    }

}

Note that now we will only send the following information to the user:

Title
Author
Number of Pages
ISBN
Rate
Status (finished or not).

A constructor was also created that will fill in your data from our DAO class.

What we learned in this tutorial

Well done! So far you have seen how to configure the database and integrate it with the system. You've also learned how to create DAO classes and DTO records for accessing database information and sending data, respectively.

In part 3 we will finish the construction of our REST API. Creating the service which will contain the business rule. And also the rest of the access routes to the system.

Creating a REST API using Spring Boot + Tests + Documentation [part 01]

Francisco Pereira — Wed, 01 Feb 2023 18:16:23 +0000

Hi!

In this 5 parts tutorial I will be teaching you how to develop a REST API using Spring Boot. In each part we will be focusing on a different functionality, this division is shown in the following table:

Part	Content
Part 01	Application Startup
Part 02	Settings and Database
Part 03	API Implementation
Part 04	Tests + Coverage
Part 05	Swagger Documentation

It is expected that from this first part you will learn the following:

Initializing a new Spring Boot application using Spring Initializr
Project structure

For this tutorial the following tools are used:

JDK 17
IntelliJ
Maven
Insomnia
MySQL database

Step 01 - Initializing the project

Spring Boot has a very simple and intuitive initialization tool, with a few steps you can already generate a Spring application with some dependencies. You can do this by going to the Spring Initializr website

For this project, we can leave the following tags and dependencies:

In the left part of the screen, we can see some technical specifications of the project.
For project management, we use Maven along with Java. The Spring Boot version we are using is 3.0.2.

In the metadata part, we mainly inform the name of the project. For this tutorial we will be creating a simple library system where we will only be storing book information. Therefore, we can name the project Simple Library.

In this tutorial we will not be exporting our project and deploying it, so we can put Packaging with its default value (.jar). However, if you are going to export this project, you can select the best option for you.

Finally, we have that the version to be used of java is 17.

In the right part of the screen we can inform Initializr which dependencies we would like to have in our project:

Spring Boot DevTools: we have access to some important developer tools, one of which is LiveReload which checks if a modification has been made to the project to restart the server automatically.
Lombok: we can insert some annotations into our classes to replace the manual insertion of getters, setters and constructors. Thus increasing developer productivity and decreasing the amount of code to be written in the class.
SpringWeb: it is one of the most important dependencies, from which we can create web services. With this dependency we can have access to the servlet-based implementation, RESTful services and many other features.

By clicking on the Explore button you will have access to the file that will be generated containing your application:

Your pom.xml file should look like this:

<?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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.0.2</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.simplelibrary</groupId>
    <artifactId>simplelibraryAPI</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>simplelibraryAPI</name>
    <description>A simple library to practice</description>
    <properties>
        <java.version>17</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

By clicking on Generate all the files needed for the application will be compressed and downloaded to your machine. From now on you can open the folder in any IDE of your choice. In this tutorial I will be using IntelliJ

Step 02 - Checking the project structure

When opening the project we can see the following structure:

📦 simplelibraryAPI
├─ src
│  ├─ main
│  │  ├─ java
│  │  │  └─ com
│  │  │     └─ simplelibrary
│  │  │        └─ simplelibraryAPI
│  │  │           └─ SimplelibraryApiApplication.java
│  │  └─ resources
│  │     ├─ db
│  │     │  └─ migration
│  │     ├─ static
│  │     ├─ templates
│  │     └─ application.properties
│  └─ test
│     └─ java
│        └─ com
│           └─ simplelibrary
│              └─ simplelibraryAPIs
│                 └─ SimplelibraryApiApplicationTests.java
├─ .mvn
├─ .gitignore
├─ mvnw
├─ mvnw.cmd
└─ pom.xml

This is the basic structure of a Spring Boot project, throughout the parts of this tutorial we will be adding new folders to keep the project more organized.

From the SimplelibraryApiApplication.java file our application will be initialized, inside this class there is the main method that will call the run method of the SpringApplication class.

package com.simplelibrary.simplelibraryAPI;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SimplelibraryApiApplication {

  public static void main(String[] args) {
    SpringApplication.run(SimplelibraryApiApplication.class, args);
  }

}

Notice the @SpringBootApplication annotation. It is important to inform Spring that this is the main class of our application and that our server will be initialized from there.

The application.properties file will contain some important properties for our system. We will understand better about it later on, especially when we are going to configure the database.

Step 03 - Running the project

After executing the previous steps, your code is ready to run. Using the IDE of your choice, when starting the server you will have the following result in the terminal:

As you can see, the server is running at address: http://localhost:8080

However, when making a request to this URL, you will find the following response from the server:


{
    "timestamp": "2023-01-31T18:08:42.607+00:00",
    "status": 404,
    "error": "Not Found",
    "message": "No message available",
    "path": "/"
}

It turns out that so far we have not mapped any route to the source url ("/"). Therefore, we need to perform the mapping, but we will see this in part 02 of our tutorial!

What we learned in this tutorial

So far, you've seen how to create the initial project in Spring Boot, using Spring Initializr. In addition to seeing a little about its structure. In part 02 we will carry out the actual implementation of our API, performing the configuration with the database and coding the access routes.