DEV Community: Alfonz Jan Frithz

Beautiful Windows Terminal on WSL with zsh

Alfonz Jan Frithz — Wed, 27 May 2020 14:54:03 +0000

Terminal Experience in Windows vs MacOS

I spend most of the time working on my personal project on MacOS and I love it. The fact that its *nix OS makes it very pleasant to work in the terminal. Customizing the terminal pretty easy compared to the limitation introduced by windows.

Don't get me wrong, I don't hate windows, I like windows, I personally use my PC when I working with something that requires a lot of resources (my pc spec is much better than my mac) such as kubernetes, docker, vargrant and many other things.

But the experience working on Windows terminal is not very pleasant. I typed 'ls for countless times on Windows terminal (and I still do). I workaround things using ConEmu but I still think it is not enough.

Pengwin and Zsh

I uninstalled my ubuntu looking for something new, I'm getting pengwin. It is an awesome alternative for WSL. Check this out and here is how the out of the box terminal looked like:

The tricky part

So when I set up my terminal with oh-my-zsh and powerlevel9k, here is how it looked like:

What happened is:

I have set up my zsh (just like when i setup it in mac, we will talk about it in the next section)
I have all the necessary fonts installed
The font still looks missing

I came to realized that there is a limitation of fonts that can be used in the terminal.

Setting up the terminal

Install oh-my-zsh

The detail of the installation is here

sudo apt install zsh
sh -c "$(curl -fsSL 
https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

Install the needed fonts

I would recommend installing nerd-fonts. Here is the one I am using, but you can use pretty much install whichever you comfortable with.

Sauce Code Pro Regular

You may download and double click and install the fonts. Sometimes the fonts are not appearing in the Properties of the terminal. And It is a limitation for us to set up a lot of things in the default terminal. So we would need a terminal wrapper. We will use mintty for WSL called wsltty

Install wsltty

The easiest is using chocolatey

choco install wsltty
Have a look at the official documentation as it might be changing time to time.
The Start menu folder WSLtty contains the link configure WSL shortcuts. This function is initially run when wsltty is installed. If should be rerun after adding or removing WSL distributions, in order to create the respective set of shortcuts in the Start menu.

Install Powerlevel9k

What you need is pretty much only to clone the powerlevel9k repository and copy the theme into oh-my-zsh theme folder. The configuration folder was generated when we installed oh-my-zsh in the previous steps. To do that we can execute this:

git clone https://github.com/bhilburn/powerlevel9k.git ~/.oh-my-zsh/custom/themes/powerlevel9k

Configure Powerlevel9k Theme

The theme could be configured in ~/.zshrc file, you may refer to show your config section in the repository.

I used this tacolizard theme for starting

Configure `wsltty`

I like to configure my terminal using darcula theme on medium opacity. We should also configure the appropriate fonts for the terminal, in this case we will use the Sauce Code Pro Regular.

Terminal settings as follows:

It now looks like the following:

I think its pretty neat!

Spring Boot REST with JPA by Example

Alfonz Jan Frithz — Sun, 24 May 2020 15:24:52 +0000

Project that we are building

We are going to build a todo list API, where we will have a Project that can have multiple topics. Each of the topics will have individual tasks.

A project could have one or more topics, and a topic will have one or more tasks.

In this post, we will integrate the existing application with Spring JPA. We will then write some integration tests to make sure our application works the way we want it. We will do it in the following sequences:

Modify our OpenAPI3 specification to accept POST request in /projects endpoint to save projects in the database.
Regenerate the code using the new specifications.
Add SpringBoot integration-test to make sure our implementation works the way we want it.
Add a POST implementation to save the Project in the database.

The source code for this post will be based on my previous post about Spring Boot Rest with OpenAPI 3. You can follow along with the previous post before follow along with this post, or you can just check out the code in this repo to get started at the same place with me.

If you are in a rush and like to see the ending instead, have a look at this repo.

If you want to know a little bit more about Spring Data JPA, here is an awesome post about The Persistent Layer with Spring Data JPA for your reference.

Introduction

As this post will guide through the implementation, if you want to directly see how the JPA implemented, instead of following along, you may scroll straight to the section of "JPA Implementation".

Write the Test

Objective

We will test the following scenarios:

Given few projects created, when user GET /projects then return all available projects
Given a project created with id 1, when user GET /projects/1 then return only project with id 1
Given a project created with name project-1, when user GET /projects?name=project-1 then return only project with name=project-1

Change the Test Mode to Spring Boot Test

@WebMvcTest is not relevant anymore in our here, because we want to perform the test up to the repository level. According to the official javadoc, it will @WebMvcTest will disable full auto-configuration and instead apply only configuration relevant to MVC tests. This mode will only relevant if only we will mock the repository & service and focus only on the testing up to the Controller.

@SpringBootTest is more relevant for our case as we will use full auto-configuration to test up to database level.

@AutoConfigureMockMvc will be required so that we could use MockMvc object when we use @SpringBootTest. It was not required as @WebMvcTest will give us that object for granted.

Here how our class going to look like now, you should be able to run this with the same result.

@SpringBootTest
@AutoConfigureMockMvc
@DisplayName("ProjectController Integration Test") // junit 5 display name. This will give us a little more flexibility to name our test
@Log4j2 // this come from lombok dependency so we could log things out
class ProjectControllerIT {
    @Autowired
    private MockMvc mockMvc;

    @Test
    @DisplayName("Should Return OK Response when request sent to /projects endpoint")
    public void shouldReturnOkOnProjectsEndpoint() throws Exception {
        mockMvc.perform(get("/projects"))
                .andExpect(status().isOk());
    }
}

Creating a helper test method to create a project

These helper method helps us to create a project from the endpoint. The snippet as follows.

class ProjectControllerIT {
  // previous snippet...

  private ProjectResponse createOneProject() {
    return createProject("project", 1).get(0);
  }

  private List<ProjectResponse> createProject(String prefix, int numberOfProject) {
    List<ProjectResponse> listOfResponse = IntStream.range(0, numberOfProject)
      .mapToObj(num -> createOneProjectWithName(format("%s-%d", prefix, num + 1)))
      .collect(Collectors.toList());

    return listOfResponse;
  }

  private ProjectResponse createOneProjectWithName(String name) {
    try {
      MvcResult result = mockMvc.perform(
        post("/projects")
          .contentType(APPLICATION_JSON)
          .content(project(name))) // we want to create the payload using this method.
        .andExpect(status().isCreated())
        .andReturn();

      String contentResponse = result.getResponse().getContentAsString();
      ProjectResponse project = ProjectModelMapper.jsonToProject(contentResponse);

      return project;
    } catch (Exception e) {
      throw new IllegalArgumentException("Invalid Request to Create Project with name" + name, e);
    }
  }
}

Notice that because we want to track what we have already created when we perform the POST, the following mapper will convert the content response to the ProjectResponse object.

// we will use this class later to also map Project from database object ot the ProjectResponse
public class ProjectModelMapper {
  private static ObjectMapper mapper = new ObjectMapper();

  public static ProjectResponse jsonToProject(String json) throws JsonProcessingException {
    return mapper.readValue(json, ProjectResponse.class);
  }
}

Another helper method we want to have in our testing is the method to create the payload that we want to send to the application so the code will be a little bit more readable.

public class ProjectRequestBuilder {
  private static ObjectMapper mapper = new ObjectMapper();

  public static String project(String name) {
    ProjectRequest pr = new ProjectRequest();
    pr.setName(name);

    return toJson(pr);
  }

  private static String toJson(Object obj) {
    try {
        return mapper.writeValueAsString(obj);
    } catch (JsonProcessingException e) {
        throw new IllegalArgumentException("Failed to parse JSON object", e);
    }
  }
}

Writing test code

We have everything we need now from the testing perspective, let's write the test code.

class ProjectControllerIT {
  // other test written before

  @Test
  @DisplayName("Should return all available projects when request sent to /projects endpoint")
  public void shouldReturnAllRecordsOnProjectsEndpoint() throws Exception {
    createProject("project", 2);

    mockMvc.perform(
      get("/projects"))
        .andExpect(status().isOk())
        .andExpect(jsonPath("$", hasSize(2)));

    createOneProject();

    mockMvc.perform(
      get("/projects"))
        .andExpect(status().isOk())
        .andExpect(jsonPath("$", hasSize(3)));
  }

  // other helper methods we wrote before
}

In this test, we will call createProject to create a Project. Behind the scene, this method which will effectively fire up a POST request to /projects. It will form the JSON payload by transforming and object into JSON representation.
We created two projects in the first call, so when we call the /projects endpoint. we should get two projects in return. When we added another one, it will return us three results.

If we run this, we will get 501 in return because we haven't implemented anything for POST to /projects

The power of MockMVC

MockMvc helps us a lot writing a test, you can imagine this as your Postman that helps you fire specific request. It could also act as your eyes to validate what you want to see in a project.

The way it structured is as follows:

Perform an action The action can be a GET/POST or any other HTTP method. If you have anything in the request that you wanted to include, e.g headers or body, you can do so in the action part.
Assert the response .andExpect methods allows you to perform quite a number of assertions of the responses. You can pretty much validate any part of the response.
Return the result You can also return the result for later use. For example, the result of the previous call will be used for the future call.

JPA Implementation

Dependencies

We need spring-boot-starter-data-jpa to helps us integrate with JPA, and we also want to use h2 database to write the implementation using in-memory database. Lets add the following dependency to the pom.xml

<!--...-->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
  <groupId>com.h2database</groupId>
  <artifactId>h2</artifactId>
  <scope>runtime</scope>
</dependency>
<!--...-->

with those packages included in our dependencies, we need to put the configuration in our resource/application.yaml as follows:

spring:
  datasource:
    url: jdbc:h2:mem:db;DB_CLOSE_DELAY=-1
    username: super
    password: secret

This tells spring how to connect tot he database.

Entity class

As we want to store a project in a database, we need an entity class representation of it. To mark a class as an entity, you may use @Entity annotation.

The JPA default table name is the name of the class (minus the package) with the first letter capitalized. Each attribute of the class will be stored in a column in the table. @Table annotation allows us to specify a table name. The others annotation is lombok annotations to keep our code concise. @Id is used to mark the field as a primary key, and we can also specify if it is coming from auto-generated value using @GeneratedValue.

Here is our entity class

@Entity
@Builder
@AllArgsConstructor
@NoArgsConstructor
@Data
@Table(name = "project")
public class Project {
  @Id
  @GeneratedValue(strategy = GenerationType.SEQUENCE)
  private Long id;
  private String name;
}

Repository to perform database operations

JPA will make things a little handy for us, what we need now is to create an interface that extends JPARepository. The first generics indicate the object that will be used and the second is the type of the key.

public interface ProjectRepository extends JpaRepository<Project, Long> { }

This alone, has already give you a methods to perform basics operation such as findAll, save, delete. We will write a bit more modification later in this post.

Next, is either we call directly from the controller layer, or we wrap it in the service layer. I would prefer to put a service layer, for us to add a business logic at some point.

@Service
public class ProjectService {
  @Autowired
  private ProjectRepository projectRepository;

  public Project createProject(Project project) {
    return projectRepository.save(project);
  }

  public List<Project> retrieveAllProjects() {
    return projectRepository.findAll();
  }
}

Notice that we actually never done any implementation to save an object, but JPARepository keep us away from creating a lot of bolierplate code e.g prepare connection, build query, extract result set, and so on, and so forth.

Query methods offers by JPARepository

Later on in this post, we will need to query a project by a project name. That would means we need to find the project by name. However, if we look at the JPARepository, there is no method to find anything by name.

To add that, we can simply add a query method in the ProjectRepository interface as the following example:

public interface ProjectRepository extends JpaRepository<Project, Long> {
    List<Project> findAllByName(String name);
}

For more details of what can the query method does, refer to official documentation.

Thats all, we are ready to call the service from the controller and run back our test.

Controller implementation

In this section, we are going to implement the project creation, to save the project into the database. We will also enhance our implementation of searchProject so it will actually returns us the actual result from the database.

At this point, we have two Project object representation, one is facing the API ProjectRequest and ProjectResponse, another one is Project entity that facing the database. Therefore, when the object returned from the Repository or Service we need a mapper to map the entity object become the response. We will write that in this section too.

@Controller
public class ProjectController implements ProjectsApi {
  @Autowired
  private ProjectService service;

  @Override
  public ResponseEntity<List<ProjectResponse>> searchProjects(@Valid String name) {
    return ResponseEntity.ok(ProjectModelMapper.toApi(service.retrieveAllProjects()));
  }

  @Override
  public ResponseEntity<ProjectResponse> createProject(@Valid ProjectRequest projectRequest) {
    Project project = service.createProject(ProjectModelMapper.toEntity(projectRequest));
    return ResponseEntity.status(CREATED).body(toApi(project));
  }
}

public class ProjectModelMapper {
  private static ObjectMapper mapper = new ObjectMapper();

  public static Project toEntity(ProjectRequest projectRequest) {
    return Project.builder()
      .name(projectRequest.getName())
      .build();
  }

  public static ProjectResponse toApi(Project project) {
    ProjectResponse projectResponse = new ProjectResponse();
    projectResponse.setId(project.getId());
    projectResponse.setName(project.getName());

    return projectResponse;
  }

  public static List<ProjectResponse> toApi(List<Project> retrieveAllProjects) {
    return retrieveAllProjects.stream()
      .map(ProjectModelMapper::toApi)
      .collect(Collectors.toList());
  }

  public static ProjectResponse jsonToProject(String json) throws JsonProcessingException {
    return mapper.readValue(json, ProjectResponse.class);
  }
}

We should get our test pass for now.

More tests

We have written 1 out of 3 test that we said we want to do in the previous section, here is the remaining:

Given a project created with id 1, when user GET /projects/1 then return only project with id 1
Given a project created with name project-1, when user GET /projects?name=project-1 then return only project with name=project-1

Lets enhance our test code. In the following test, we will try to get the project by id. Given that the project created, we should be able to retrieved the project using the id that was returned before.

@Test
@DisplayName("Should be able to retrieve project by project id")
public void shouldRetrieveExistingProject() throws Exception {
  ProjectResponse project = createOneProjectWithName("project-1");

  Long projectId = project.getId();
  mockMvc.perform(
    get("/projects/" + projectId))
    .andExpect(status().isOk())
    .andExpect(jsonPath("$.name", is("project-1")))
    .andExpect(jsonPath("$.id", is(projectId.intValue())));
}

Obviously the test will fail, and returns us 501 errors indicating the functionality is not implemented yet. We should then enhance our controller to include the following methods.

@Override
public ResponseEntity<ProjectResponse> getProjects(@Min(1L) Long projectId) {
  Project project = service.findProject(projectId);
  return ResponseEntity.ok().body(toApi(project));
}

as findProject methods havent been implemented yet, lets get that implemented in our service level. The getOne method is the method that came with JPARepository we do not need to modify our repository implementation at this point.

public Project findProject(Long projectId) {
    return projectRepository.getOne(projectId);
}

And we got the new test pass now. However, we breaks the previous test. The reason why is because, the previous test was retrieving all the projects, but because of we have another test that is also adding the project into the database, the number doesn't add up correctly. The solution is pretty simple, we should reset the database state before we executing any test. To make sure our test is independent of each other.

We can add the following method into our test, this will make sure we clear up the project table before any test is executing.

@Autowired
private JdbcTemplate jdbcTemplate;

@BeforeEach
void setUp() {
  log.info("Deleting records from table");
  JdbcTestUtils.deleteFromTables(jdbcTemplate, "project");
}

Now all of our tests is passed again. The last bit of the test before we wrap up with this post is the following feature:

Given a project created with name project-1, when user GET /projects?name=project-1 then return only project with name=project-1

So here is the test:

@Test
@DisplayName("Should be able to search project by name")
public void shouldRetrieveExistingProjectByName() throws Exception {
  ProjectResponse projectOne = createOneProjectWithName("Project One");
  ProjectResponse projectTwo = createOneProjectWithName("Project Two");

  mockMvc.perform(
    get("/projects").param("name", "Project One"))
    .andExpect(status().isOk())
    .andExpect(jsonPath("$", hasSize(1)))
    .andExpect(jsonPath("$[0].id", is(projectOne.getId().intValue())))
    .andExpect(jsonPath("$[0].name", is(projectOne.getName())));

  mockMvc.perform(
    get("/projects").param("name", "Project Two"))
    .andExpect(status().isOk())
    .andExpect(jsonPath("$", hasSize(1)))
    .andExpect(jsonPath("$[0].id", is(projectTwo.getId().intValue())))
    .andExpect(jsonPath("$[0].name", is(projectTwo.getName())));

  mockMvc.perform(
    get("/projects").param("name", "Project X"))
    .andExpect(status().isOk())
    .andExpect(jsonPath("$", hasSize(0)));
}

Again, we will fail the test because we haven't get any implementation in our controller to filter the projects by name. It should complain that the number of returned project is more than what we expect. Let's fix the code to accomodate that.

We don't have findProjectsByName yet in our service, we may need that so our controller can use it to get some data from the repository. So lets add the new method to help us get the Project by name. We have findAllByName query methods added before.

public List<Project> findProjectsByName(String name) {
  return projectRepository.findAllByName(name);
}

At this point, what we need to do is to enhance our controller, to perform a search by name, if there is a name specified, otherwise, we will return all projects.

@Override
public ResponseEntity<List<ProjectResponse>> searchProjects(@Valid String name) {
  if (name != null) {
    return ResponseEntity.ok(ProjectModelMapper.toApi(service.findProjectsByName(name)));
  } else {
    return ResponseEntity.ok(ProjectModelMapper.toApi(service.retrieveAllProjects()));
  }
}

Wrap Up

Here is what we did so far:

Modify our OpenAPI3 specification to accept POST request in /projects endpoint to save projects in the database.
Regenerate the code using the new specifications.
Add SpringBoot integration-test to make sure our implementation works the way we want it.
Add a POST implementation to save the Project in the database.

To see the complete source code, you may checkout the repo in my github here

Spring Boot REST with OpenAPI 3

Alfonz Jan Frithz — Mon, 18 May 2020 00:43:05 +0000

Project that we are building

We are going to build a todo list API, where we will have a Project that can have multiple topics. Each of the topics will have individual tasks.

A project could have one or more topics, and a topic will have one or more tasks.

In this post, we will have the project set up and API specification defined. We will then write some basic test, and integrating the generated code with our project. We will do it in the following sequences:

Defining the API with OpenAPI3 specification.
Cover a little bit about the common parts of the OpenAPI3
Generate API code in spring boot using openapi-generator-maven-plugin (we will stick to maven now)
Write tests to make sure our application works the way we want it.

If you are in a rush, and you prefer to see the ending instead, have a look at this repo instead. It has the end state of this post.

OpenAPI 3 Specification

Introduction

I summarize the definition from the official website as follows:

OpenAPI Specification is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including available endpoint and operations, operation, examples, authentication method and other supporting information such as contact name, or host.

Having a standard for defining API, enables us to do a lot more automation utilizing those templates such as:

Generating API Documentation
Stubs/Mocks
Communication tools for stakeholders
Controlling changes of API version.

We can write OpenAPI3 specifications in JSON/YAML format. But in this post, we will write the definition in YAML format (I think it's easier for the eye).

To help us writing the specs, we can use swagger editor online or locally using docker image.

Swagger Editor

Swagger Editor helps us write API Specification with some UI to ease our development.

Swagger editor available online in editor.swagger.io or if you want it to be in your local, you can spin up the docker container

docker pull swaggerapi/swagger-editor
docker run -d -p 80:8080 swaggerapi/swagger-editor

We will use swagger-editor throughout the post.

Defining the API

Metadata & Servers

This is useful to give information about the API and possibly the location of the API servers, so the user could have a try out on the API to the endpoints defined in the server section. The specification looks as follows:

# OpenAPI 3 has quite a difference with OpenAPI 2, the way the linter works in the editor will be based on this.
openapi: 3.0.0  

# This section will contain metadata information about the API. It will be shown on the editor/UI when we publish this
info:
  title: To-Do Board API
  version: 1.0.0
  description: API specification to support daily to-do list operations

# The list of the servers that we can use to use the API. This will be rendered as a combo box in the editor/UI when we publish it, so the user could pick and use the endpoint they prefer.
servers:
  - url: http://dev-api.todoboard.com/v1
    description: DEV-ENV
  - url: http://api.todoboard.com/v1
    description: PROD-ENV

paths: {}

You may put those in swagger editor and you will see a bit of progress there. We move on!

Paths & Operation

In this section, we are putting a little bit more functionality to our API. We will create an endpoint to retrieve a project as well as topics from a project.

Let's replace paths: {} from the previous section to be a little more meaningful.

paths:
  /projects: # the API path in which the operation will be performed. When this endpoint triggered, the operation meant to be executed.
    get: # the HTTP method
      parameters:
        - in: query
          description: find project by name
          name: name
          schema:
            type: string
      operationId: searchProjects # optional unique string used to identify an operation. When the code generated, this will be the method name.
      tags:
        - Projects # group operations logically by resources or any other qualifier. In the context of spring code generation, tags is going to be the class name.
      description: retrieve all available projects in paginated way
      responses:
        200:
          description: successfully retrieved all projects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProjectResponse'

  /projects/{projectId}:
    get:
      operationId: getProjects
      tags:
        - Projects
      description: retrieve a project by id
      parameters:
        - name: projectId
          in: path
          schema:
            type: integer
            format: int64
            minimum: 1
          required: true
          allowEmptyValue: false
          example: 1

      responses:
        200:
          description: the specific project successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'

There are few things that quite important here:

the individual path I think this is pretty self-explanatory, this will be the API path in which the operation will be performed. When this endpoint triggered, the operation meant to be executed.
method of operation This is the HTTP method. OpenAPI 3.0 supports get, post, put, patch, delete, head, options, and trace.
operationId operationId is an optional unique string used to identify an operation. If provided, these IDs must be unique among all operations described in your API. In the context of spring code generation, operationId will be the method name that we will need to implements.
Tags used to group operations logically by resources or any other qualifier. In the context of spring code generation, tags is going to be the class name.
Parameters OpenAPI 3.0 supports operation parameters passed via path, query string, headers, and cookies. We can have some specifications of the parameter, e.g whether one is required, data type, etc.
Schema we can define an object that we are going to use in our request/response in a schema. It is good if we have repeated objects that we can use in multiple places

Components

If you notice, both of the responses in both paths above referring to a component called Projects which, the editor might be complaining because we haven't defined it yet.

Let's update our code as follows:

components:
  schemas:
    ProjectResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: unique id of the project for the identifier
          example: 1
        name:
          type: string
          description: the name of the project
          example: To-do Application Development

Now that we have the OpenAPI3 definition ready, we will use that as the basis of our operation. Some parts of our code will be automatically generated based on the specification. We will talk more details in the next section.

Spring Boot Application

Although not all the functionality exists in the API definition (we will save that for another post), we can get started to write the application. Here is what we are gonna do:

Set up maven project with few dependencies as follows:
- spring-boot-starter-web Starter for building web, including RESTful, applications using Spring MVC. Uses Tomcat as the default embedded container
- spring-boot-starter-test (we can exclude the vintage engine) Starter for testing Spring Boot applications with libraries including JUnit, Hamcrest, and Mockito
- springfox-swagger2 we will use the Springfox implementation of the Swagger specification.
Set up maven build with the following plugins
- spring-boot-maven-plugin The Spring Boot Maven Plugin provides Spring Boot support in Maven, allowing you to package executable jar or war archives and run an application “in-place”.
- openapi-generator-maven-plugin A Maven plugin to support the OpenAPI generator project
Write an integration test to verify the API is working as per expected using WebMvcTest & MockMvc

Project Setup

We can use Spring Initializer to create our project template. We can add Spring Web dependency, so that spring initializer adds half of our needed dependencies.

Add the remaining dependency so the pom.xml looks like the following snippet (ignoring some parts of the pom to save the space, refer to the repository for the exact code):

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>

  <!--Required for swagger code generation-->
  <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
  </dependency>

  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
    <exclusions>
      <exclusion>
        <groupId>org.junit.vintage</groupId>
        <artifactId>junit-vintage-engine</artifactId>
      </exclusion>
    </exclusions>
  </dependency>
</dependencies>

<build>
  <plugins>
    <plugin>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-maven-plugin</artifactId>
    </plugin>

    <!--
    * This plugin is used to handle the code generation with the configuration defined in openapi-generator-config.json
    * the openapi specification will be placed in api.yaml as an imput spec
    -->
    <plugin>
      <groupId>org.openapitools</groupId>
      <artifactId>openapi-generator-maven-plugin</artifactId>
      <version>3.3.4</version>
      <executions>
        <execution>
          <goals>
            <goal>generate</goal>
          </goals>
          <configuration>
            <inputSpec>${project.basedir}/src/main/docs/api.yaml</inputSpec>
            <configurationFile>${project.basedir}/openapi-generator-config.json</configurationFile>
            <ignoreFileOverride>${project.basedir}/.openapi-generator-ignore</ignoreFileOverride>
            <generatorName>spring</generatorName>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

API Code Generation

As mentioned in the pom, there are few files we need to take care of as follows:

api.yml this is where we place all of the defined API that we worked on earlier. In our case, we will put it in /main/docs/api.yaml.
openapi-generator-config.json This file contains the configuration for the openapi-codegen to know what and how to generate the code. Refer to the official documentation for available options. In our case, we will put it in the main project directory.
.openapi-generator-ignore we want to be a little bit more flexible and exclude some of the classes that we want to define ourselves, e.g Controller classes. In our case, we will put it in the main project directory.

openapi-generator-config.json

This file contains the configuration on how the openapi generator will behave. We can put this configuration under <configuration> in the pom, but I thought its easier to manage it externally.

For other configuration refer to the official repository

{
  "java8": "true",
  "dateLibrary": "java8",
  "useBeanValidation": "true",
  "useTags": "true",
  "generateApiTests": "false",
  "generateApiDocumentation": "false",
  "supportingFiles": "false",
  "serializableModel": "true",
  "basePackage": "com.alfonzjanfrithz.todoboard",
  "modelPackage": "com.alfonzjanfrithz.project.todoboard.model",
  "apiPackage": "com.alfonzjanfrithz.project.todoboard.api",
  "configPackage": "com.alfonzjanfrithz.project.todoboard.config"
}

.openapi-generator-ignore

And because we don't want to use everything from the generated class, we can actually get a few files ignored by mentioning it in the file that we put in <ignoreFileOverride>.

**/OpenAPI2SpringBoot.java
**/*Controller.java

Implementation

Write an Integration Test

Time to put some implementation in the code, I like to build a habit to write a test first before real implementation. We will put some basic implementation on the controller, write a test, and fix the test along the way.

We can now implement the *Api interfaces generated from swagger, so we don't need to implement things like @RequestMapping and all the parameters/headers. The plugins generated those boilerplate and hide it in the interfaces it generates. As they have the default implementation in the interface, we can leave the implementation blank and implement it later.


// /main/controller/ProjectController.java
@Controller
public class ProjectController implements ProjectsApi {

}

// /test/controller/ProjectController.java
@WebMvcTest
class ProjectControllerIT {
    @Autowired
    private MockMvc mockMvc;

    @Test
    @DisplayName("OK Response when request sent to /projects endpoint")
    public void shouldReturnOkOnProjectsEndpoint() throws Exception {
        mockMvc.perform(MockMvcRequestBuilders.get("/projects"))
                .andExpect(status().isOk());
    }
}

We will get fail test now because the method that is not implemented:

java.lang.AssertionError: Status expected:<200> but was:<501>
Expected :200
Actual   :501

Controller implementation

@Controller
public class ProjectController implements ProjectsApi {
    @Override
    public ResponseEntity<List<ProjectResponse>> searchProjects(@Valid String name) {
        return ResponseEntity.ok(Collections.emptyList());
    }
}

Our test is passed now and we can follow up with more tests and implementations.

If you are interested in further implementation that based on this project, have a look at the following post:

Spring Data JPA by Example

DEV Community: Alfonz Jan Frithz

Beautiful Windows Terminal on WSL with zsh

Terminal Experience in Windows vs MacOS

Pengwin and Zsh

The tricky part

Setting up the terminal

Install oh-my-zsh

Install the needed fonts

Install wsltty

Install Powerlevel9k

Configure Powerlevel9k Theme

Configure wsltty

Spring Boot REST with JPA by Example

Project that we are building

Introduction

Write the Test

Objective

Change the Test Mode to Spring Boot Test

Creating a helper test method to create a project

Writing test code

The power of MockMVC

JPA Implementation

Dependencies

Entity class

Repository to perform database operations

Query methods offers by JPARepository

Controller implementation

More tests

Wrap Up

Spring Boot REST with OpenAPI 3

Project that we are building

OpenAPI 3 Specification

Introduction

Swagger Editor

Defining the API

Metadata & Servers

Paths & Operation

Components

Spring Boot Application

Project Setup

API Code Generation

openapi-generator-config.json

.openapi-generator-ignore

Implementation

Write an Integration Test

Controller implementation

Configure `wsltty`