Forem: Funmi Olaiya

Get started with NestJS and create a todo "notes" app: documenting the API endpoints with NestJs swagger (Part 3)

Funmi Olaiya — Sat, 09 May 2020 09:44:35 +0000

Hey,

Nice to see you here again, if you have been following these series from the beginning,

For the part1: https://dev.to/funmi5/get-started-with-nestjs-and-create-a-todo-notes-app-4c67

I wrote about how to create a todo app with Nestjs and why I would consider the NestJs framework for future projects.

For the part2: https://dev.to/funmi5/get-started-with-nestjs-and-create-a-todo-notes-app-creating-e2e-tests-part-2-5pl

I wrote on how to create end-to-end tests using the inbuilt Testing module of NestJs.

Now, this article will be the last part of the series and we will learn how to document the API endpoints we have built earlier using the inbuilt swagger module of NestJs.

Let's get started:

Originally, I do not use Swagger to document an API endpoint I work on, I prefer Apiary/API Blueprint because of the user interface, simplicity and the fact that it is easy to set up using the JSON format.

But alas, NestJs is different, you can document an API as you are building, everything syncs together with the code. Isn't that great?!

Install the following command:

The package will allow us to use configure and use the swagger module.

npm install @nestjs/swagger swagger-ui-express -S

Now we have to configure and initialize swagger in the main.ts file

Modify the file to the following code:

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { SwaggerModule, DocumentBuilder } from "@nestjs/swagger";
import { NoteModule } from "../src/modules/note.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.setGlobalPrefix("api/v1");

  const options = new DocumentBuilder()
    .setTitle("Notes todo app")
    .setDescription(
      "A documentation for notes"
    )
    .setVersion("1.0")
    .addTag("Notes")
    .build();
  const apppDocument = SwaggerModule.createDocument(app, options, {
    include: [NoteModule]
  });
  SwaggerModule.setup("api", app, apppDocument);
  await app.listen(3000);
}
bootstrap();

Note:

The DocumentBuilder() helps to structure a document that takes in different properties for configuration.
Read more and extensively here: https://docs.nestjs.com/recipes/swagger#openapi-swagger

Next, the data-transfer-object(dto) has to be configured:

In the note.dto.ts file, modify it to the following code:

import { ApiProperty } from "@nestjs/swagger";

export class CreateNoteDTO {
    @ApiProperty()
    name: string;

    @ApiProperty()
    description: string;

    @ApiProperty()
    tags: string;
}

Note:

to annotate all Api properties, the @ApiProperty decorator is used.

The controllers have to be modified too, to the following code:

import { Controller, Res, HttpStatus, Post, Get, Param, Body, Patch, Query, Delete } from "@nestjs/common";
import { NoteService } from "../services/note.service";
import { CreateNoteDTO } from "../dtos/note.dto";
import { ApiResponse, ApiTags } from "@nestjs/swagger";

@ApiTags("Notes")
@Controller('note')
export class NoteController {
    constructor(private noteService: NoteService) { }

    @ApiResponse({ status: 201 })
    @Post('/add')
    async createANote(@Res() res, @Body() createNoteDTO: CreateNoteDTO) {
        const note = await this.noteService.createANote(createNoteDTO);
        return res.status(HttpStatus.CREATED).json({
            status: 201,
            message: "Successful!",
            data: note
        })
    }

    @ApiResponse({ status: 200 })
    @Get('/all')
    async getAllNotes(@Res() res) {
        const notes = await this.noteService.getAllNotes();
        return res.status(HttpStatus.OK).json({
            status: 200,
            data: notes
        })
    }

    @ApiResponse({ status: 200 })
    @Get("/:noteId")
    async getANote(@Res() res, @Param("noteId") _id: string) {
        const note = await this.noteService.getANote(_id);
        if (!note)
            return res
                .status(HttpStatus.NOT_FOUND)
                .json({ status: 404, error: "Not found!" });
        return res.status(HttpStatus.OK).json({ status: 200, data: note });
    }

    @ApiResponse({ status: 200 })
    @Patch('/update/:noteId')
    async updateCustomer(@Res() res, @Body() createNoteDTO: CreateNoteDTO, @Param("noteId") _id: string) {
        const note = await this.noteService.updateANote(_id, createNoteDTO);
        if (!note)
            return res
                .status(HttpStatus.NOT_FOUND)
                .json({ status: 404, error: "Not found!" });
        return res.status(HttpStatus.OK).json({
            status: 200,
            message: 'Successful!',
            note
        });
    }

    @ApiResponse({ status: 200 })
    @Delete('/delete/:noteId')
    async deleteCustomer(@Res() res, @Param('noteId') _id) {
        const note = await this.noteService.deleteANote(_id);
        if (!note)
            return res
                .status(HttpStatus.NOT_FOUND)
                .json({ status: 404, error: "Not found!" });
        return res.status(HttpStatus.OK).json({
            status: 200,
            message: 'Successful!',
        })
    }

}

Note:

the @ApiTags is used to annotate the class and return it.
to specify and return the response type, the @ApiResponse property is used to annotate the methods.
read more about short-hand API response decorators for swagger on the official docs.

Run:

npm run start:dev

and you'll see the documented APIs at localhost:3000/api

That marks the end of these series...

For the full code: https://github.com/funmi5/nestjs-notes-todo

Thanks for reading.

Get started with NestJS and create a todo "notes" app: creating e2e tests (Part 2)

Funmi Olaiya — Sat, 09 May 2020 09:42:22 +0000

Welcome back!

If you read my last post: https://dev.to/funmi5/get-started-with-nestjs-and-create-a-todo-notes-app-4c67

I wrote a comprehensive walkthrough on how to get started with using the NestJs framework, my general overview of it and why it should be considered for future projects.

Now, we are back to the part 2 of the post which is about writing end-to-end tests.

My understanding of end-to-end testing and why it is important is that it helps to test an application's workflow from start to finish, it helps to test the endpoints by behaving the way a real user would.

Why I totally love end-to-end testing is because it helps to prevent silly bugs and of course regression - this works in a way that bugs make a feature stop working after on update/upgrade.

Let's get started:

In the project created last time, check the tests folder and you will see that a test had already been created for the entry GET route upon creation - app.e2e-spec.ts.

HTTP requests are simulated using the supertest library.
Then we initiate a request to the app that looks like that of a real HTTP request.
Please, read more about the INestApplication interface, the inbuilt NestJs TestingModule and the flow of operation from the official docs on automated testing here: - https://docs.nestjs.com/fundamentals/testing

Modify the e2e jest config to:

changing the regex from e2e-spec.ts to e2e.ts

{
  "moduleFileExtensions": [
    "js",
    "json",
    "ts"
  ],
  "rootDir": ".",
  "testEnvironment": "node",
  "testRegex": ".e2e.ts$",
  "transform": {
    "^.+\\.(t|j)s$": "ts-jest"
  }
}

Create a file called note.e2e.ts in your tests folder.

Add the following code:

import { Test, TestingModule } from "@nestjs/testing";
import { INestApplication, HttpStatus } from "@nestjs/common";
import * as request from "supertest";
import { AppModule } from "../src/app.module";
import { CreateNoteDTO } from "../src/dtos/note.dto";
import * as mongoose from "mongoose";

describe("E2E Tests for NOTE Endpoints", () => {
    let app: INestApplication;

    beforeEach(async () => {
        jest.setTimeout(10000);
        const moduleFixture: TestingModule = await Test.createTestingModule({
            imports: [AppModule],
        }).compile();

        app = moduleFixture.createNestApplication();
        await app.init();
    });

    afterAll(async done => {
        await mongoose.disconnect(done);
    });

    it("should create a note", () => {
        const note: CreateNoteDTO = {
            name: "My Travel Plans for 2020",
            description: "Plans to travel to Kenya",
            tags: "Travel",
        };
        return request(app.getHttpServer())
            .post("/note/add")
            .set("Accept", "application/json")
            .send(note)
            .expect(HttpStatus.CREATED);
    });
    it("should update a note", () => {
        const note: CreateNoteDTO = {
            name: "My Travel Plans for 2020",
            description: "Plans to travel to Kenya",
            tags: "Work",
        };
        return request(app.getHttpServer())
            .patch("/note/update/5ead5c1a43ace404e06a7408")
            .set("Accept", "application/json")
            .send(note)
            .expect(HttpStatus.OK);
    });
    it("should get all notes", () => {
        return request(app.getHttpServer())
            .get("/note/all")
            .set("Accept", "application/json")
            .expect(HttpStatus.OK);
    });
    it("should get a note", () => {
        return request(app.getHttpServer())
            .get("/note/5ead5c1a43ace404e06a7408")
            .set("Accept", "application/json")
            .expect(HttpStatus.OK);
    });
    it("should delete a note", () => {
        return request(app.getHttpServer())
            .delete("/note/delete/5ead5c1a43ace404e06a7408")
            .set("Accept", "application/json")
            .expect(HttpStatus.OK);
    });
});

And there you have it. We have successfully created e2e tests for the endpoints!

For part 1: https://dev.to/funmi5/get-started-with-nestjs-and-create-a-todo-notes-app-4c67
For part 3: https://dev.to/funmi5/get-started-with-nestjs-and-create-a-todo-notes-app-documenting-the-api-endpoints-with-nestjs-swagger-part-3-67

For the code: https://github.com/funmi5/nestjs-notes-todo

Get started with NestJS and create a todo "notes" app.

Funmi Olaiya — Sat, 02 May 2020 15:54:53 +0000

Recently, I took part in a challenge to work on a mini NestJS app and I fell in love with the framework.

The architecture?
Easy to set-up CLI?
or the fact that it fully supports the use of typescript?

The three points mentioned above made the experience wonderful and I'll be using NestJs for my future projects.

According to the official docs, it is deemed a progressive Node.js framework for building efficient, reliable and scalable server-side applications.
Check out the docs: https://docs.nestjs.com/

I use NodeJS and the express framework for back-end web development. Express is known and good for setting up quick, reliable and fast APIs but it does not enforce any architecture or solid principles of OOP, and this is exactly where Nestjs comes in.

Few interesting facts I got from using NestJs:

It enforces an architecture that ensures the developed/developing app is modular.
It is very easy to document APIs using nestJs/swagger, as it can easily be incorporated when the API routes are being designed.
It contains all the features you need at the beginning of the project - this happens when you create a new app with the CLI.
It helps to consistently demand the best logic and practice when developing new APIs - the reason being that you can not easily do a manipulation.
It fits so perfectly with the use of the mongoose ODM and typescript - it helps the more if you are experienced in using mongoose with express.
Who is happy with me? Yes, we can finally do away with babel.

A quick overview of how our app architecture will be structured:

Let us get started with creating to understand better.

Install nestjs and create an app using the following commands:

npm i -g @nestjs/CLI

After the installation is successful run,

npm install

Then create a new nest project,

nest new project-name

Since we are going to be using mongoose with NestJs, we have to install some packages.

npm install mongoose -S
npm install @nestjs/mongoose -S
npm install dotenv -S
npm install @types/dotenv -S

Create a database connection using the atlas mongodb connection string.

I am assuming you can set up a new cluster on mongodb called notes-todo.
If you have set up the database and gotten the connection string, good!

In your src folder, create folders called schemas, interfaces, dtos, services and controllers.

Creating a schema.

A schema will determine how the data should be stored in the database.

Create a file in the schemas folder called note.schema.ts

Add the following code:

import * as mongoose from "mongoose";
const { Schema } = mongoose;

export const NoteSchema = new Schema({
    name: String,
    description: String,
    tags: {
        type: String,
        enum: ["Personal", "Travel", "Life", "Work"],
    },
});

Create a file in the interfaces folder called note.interface.ts

An interface defines the kind of values(type-checking) the application must adhere to/receive.
The readonly keyword depicts that the values can be accessed outside of the class but cannot be modified.

Add the following code:

import { Document } from "mongoose";

export interface Note extends Document {
    readonly name: string;
    readonly description: string;
    readonly tags: string;
    readonly createdAt: Date;
}

Create a file in the dtos folder called note.dto.ts

A DTO(data transfer object) depicts what the expected request should look like.

Add the following code:

export class CreateNoteDTO {
    name: string;
    description: string;
    tags: string;
    createdAt: Date;
}

Create the service provider class and methods for all the routes:

In the services folder, create a file named note.service.ts

Add the following code:

import { Injectable } from "@nestjs/common";
import { Model } from "mongoose";
import { InjectModel } from "@nestjs/mongoose";
import { Note } from "../interfaces/note.interface";
import { CreateNoteDTO } from "../dtos/note.dto";

@Injectable()
export class NoteService {
    constructor(@InjectModel("Note") private readonly noteModel: Model<Note>) { }
    async createANote(createNoteDTO: CreateNoteDTO): Promise<Note> {
        const newNote = await this.noteModel(createNoteDTO);
        return newNote.save();
    }

    async getAllNotes(): Promise<Note[]> {
        const notes = await this.noteModel.find().exec();
        return notes;
    }

    async getANote(noteId): Promise<Note> {
        const note = await this.noteModel.findById(noteId).exec();
        return note;
    }

    async updateANote(_id, createNoteDTO: CreateNoteDTO): Promise<Note> {
        const note = await this.noteModel.findByIdAndUpdate(_id, createNoteDTO, { new: true });
        return note;
    }

    async deleteANote(_id): Promise<any> {
        const note = await this.noteModel.findByIdAndRemove(_id);
        return note;
    }
}

Note:

@Injectable is a decorator that allows classes to be made available and be a provider.
A NoteService function is created and the note interface is injected through the class constructor using the decorator @InjectModel from nestjs/mongoose.
The NoteService class takes in five methods to help design the API routes.
The main use of these methods is to abstract the logic away.

Creating the controller class and methods for all the routes:

In the controllers folder, create a file named note.controller.ts

Add the following code:

import { Controller, Res, HttpStatus, Post, Get, Param, Body, Patch, Delete } from "@nestjs/common";
import { NoteService } from "../services/note.service";
import { CreateNoteDTO } from "../dtos/note.dto";

@Controller('note')
export class NoteController {
    constructor(private noteService: NoteService) { }

    @Post('/add')
    async createANote(@Res() res, @Body() createNoteDTO: CreateNoteDTO) {
        const note = await this.noteService.createANote(createNoteDTO);
        return res.status(HttpStatus.CREATED).json({
            status: 201,
            message: "Successful!",
            data: note
        })
    }

    @Get('/all')
    async getAllNotes(@Res() res) {
        const notes = await this.noteService.getAllNotes();
        return res.status(HttpStatus.OK).json({
            status: 200,
            data: notes
        })
    }

    @Get("/:noteId")
    async getANote(@Res() res, @Param("noteId") _id: string) {
        const note = await this.noteService.getANote(_id);
        if (!note)
            return res
                .status(HttpStatus.NOT_FOUND)
                .json({ status: 404, error: "Not found!" });
        return res.status(HttpStatus.OK).json({ status: 200, data: note });
    }

    @Patch('/update/:noteId')
    async updateCustomer(@Res() res, @Body() createNoteDTO: CreateNoteDTO, @Param("noteId") _id: string) {
        const note = await this.noteService.updateANote(_id, createNoteDTO);
        if (!note)
            return res
                .status(HttpStatus.NOT_FOUND)
                .json({ status: 404, error: "Not found!" });
        return res.status(HttpStatus.OK).json({
            status: 200,
            message: 'Successful!',
            note
        });
    }

    @Delete('/delete/:noteId')
    async deleteCustomer(@Res() res, @Param('noteId') _id) {
        const note = await this.noteService.deleteANote(_id);
        if (!note)
            return res
                .status(HttpStatus.NOT_FOUND)
                .json({ status: 404, error: "Not found!" });
        return res.status(HttpStatus.OK).json({
            status: 200,
            message: 'Successful!',
        })
    }

}

Note:

A class called NoteController is created and the provider - NoteService is injected through the class constructor.
The five methods created within the class controller are only created to handle the incoming requests. Remember that all the logic have been abstracted away with the providers.

Create a feature module for the provider and the controller:

The purpose of a feature module is to simply organize code and establish boundaries and this principle makes more sense if the application is bound to keep growing, it is used with the @Module decorator.

In the modules folder, create a file named note.module.ts

Add the following code:

import { Module } from '@nestjs/common';
import { MongooseModule } from '@nestjs/mongoose';
import { NoteController } from "../controllers/note.controller";
import { NoteService } from "../services/note.service";
import { NoteSchema } from "../schemas/note.schema";

@Module({
    imports: [
        MongooseModule.forFeature([{ name: 'Note', schema: NoteSchema }])
    ],
    controllers: [NoteController],
    providers: [NoteService]
})
export class NoteModule { }

The root module needs to be modified:

The module is the start point of the application graph and it encapsulates providers by default, but since we already have a defined feature module, all we need to do is import that feature module and schema into this root module.

In the app.module.ts

Modify it by adding the following code:

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { MongooseModule } from '@nestjs/mongoose';
import { NoteModule } from './modules/note.module';
import "dotenv/config";

@Module({
  imports: [
    MongooseModule.forRoot(process.env.DATABASE_URI,
      {
        useNewUrlParser: true,
        useUnifiedTopology: true,
        useCreateIndex: true,
        useFindAndModify: false
      }),
    NoteModule
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule { }

Finally:

In order to add an API version, we are going to use nestjs setGlobalPrefix

In the main.ts

Modify it by adding the following code:

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.setGlobalPrefix("api/v1");
  await app.listen(3000);
}
bootstrap();

Add the connection string to your .env file

example: DATABASE_URI = mongodb+srv://<username>:<pasword>@cluster0-xydxj.mongodb.net/notes_db

Run npm run start:dev

These API routes should be able to function:

localhost:3000/api/v1/notes/add
localhost:3000/api/v1/notes/all
localhost:3000/api/v1/notes/:noteId
localhost:3000/api/v1/notes/update/:noteId
localhost:3000/api/v1/notes/delete/:noteId

KeyNote: Read up more on Dependencies, Decorators, Modules, Providers and Controllers on the official docs: docs.nestjs.com

For part 2: https://dev.to/funmi5/get-started-with-nestjs-and-create-a-todo-notes-app-creating-e2e-tests-part-2-5pl

For part 3: https://dev.to/funmi5/get-started-with-nestjs-and-create-a-todo-notes-app-documenting-the-api-endpoints-with-nestjs-swagger-part-3-67

For the code - https://github.com/funmi5/nestjs-notes-todo

Mini contact cards - using Algolia as the search service and setting the web app up as a PWA

Funmi Olaiya — Wed, 19 Feb 2020 21:50:43 +0000

Hello everyone,

This tutorial will be about getting few details from a JSON object as mini contact cards using the front-end technology(react) and a search engine(algolia). The app will be hosted on netlify.

A quick note:

Algolia is a powerful search-service because the set up is quite easy, powerful, produces excellent search results and allows users to have a wonderful search experience.

Let's get started:

-Make sure Node.js installed on your computer

Set up react using this command - npx create-react-app . not npx create-react-app my-app because the later command will install a folder into the folder you already specified and we want the folder structure to look like this:

Read more:- https://create-react-app.dev/docs/getting-started/

In the App.js file, refactor the code to the following code:

import React, { Component} from 'react';
import './App.css';

class App extends Component {

    render(){
    return (
      <div className="App">
          <p>Random contact card</p>
    </div>
    );
    }
  }

  export default App;

We only need to render the title of the app for now.

Add this to the App.css file:

p {
    font-size: 50px;
    color: rgb(164, 193, 188);
    text-align: center
  }

In the index.css file, refactor the code to the following code:

body {
  margin: 0;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

An account needs to be created on algolia and once that is created, you will be redirected to a dashboard.

Create an index titled -, for example: search-details.

Under add records to search, there are three options, add records manually, use the API or upload file.

We will be uploading the records manually since they are just ten users we are trying to search for.

Paste this JSON URL in your browser to get the full data: http://jsonplaceholder.typicode.com/users

After the full data have been copied, paste it to the algolia console and click save.

Click on searchable attributes and add the attributes to be used in searching.
Tip: you can add name and email since that is what will only be searched for.
Review and save settings.

Create a folder called components and create another folder called search, in it, create two files called - search.component.jsx and search.style.css in the search folder.

Install these packages:
npm install aloglia search react-instantsearch-dom -S - to integrate the Javascript API client and for helping to search the react-dom.

Add this following code to the search.component.jsx file:

import React from 'react';
import algoliasearch from 'algoliasearch/lite';
import { InstantSearch, SearchBox} from 'react-instantsearch-dom';
import {Content} from '../content/content.component';
import './search.style.css';

const searchClient = algoliasearch(
  '_APP ID_',
  '_Search-Only API Key_'
);
export const Search = () => (
  <InstantSearch searchClient={searchClient} indexName="search-details">
         <SearchBox 
            className='search' 
            />
     <Content 
     />    
  </InstantSearch>
);

algolisearch app id and key are assigned to a constant whereby a function is declared to use the instantsearch component, retrieve the searchClient and index of the records.
The searchBox is a widget used to let the user perform a text-based query - will be used for searching through the records.

Add this code to the search.style.css:

input[type='search'] {
    justify-content: center;
    padding: 10px 30px;
    width: 40%;
    border: 1px solid black;
    margin-left: 30%;
  }

button.ais-SearchBox-submit {
      display: none;
  }

button.ais-SearchBox-reset{
  display: none;
}

Back to the components folder:

Create a folder called content, in it, create two files called: content.component.jsx and content.style.css.

Add the following code to the content.component.jsx file:

import React from 'react';
import { Hits } from 'react-instantsearch-dom';
import { Hit } from '../hit/hit.component';
import './content.style.css';

export const Content =() => (
<div className = 'content'>
    <Hits hitComponent={Hit} />
    </div>
);

This code merely houses the imported hit component.

Add this code to the content.style.css file:

ul {
  list-style-type: none;
  width: 60%;
  margin: 0 auto;
  margin-top: 5%;
  }

  li {
  margin: 1em 0;
  }  


  @media screen and (max-width: 600px) {
    ul {
      width: 70%;
      margin-left: 5%;
    }
}

Back to the components folder:
Create a folder called hit, in it, create two files called: hit.component.jsx and hit.style.css.

Add the following code to the hit.component.jsx file:

import React from 'react';
import './hit.style.css';

export const Hit = ({ hit }) => (
    <div className="hit">
        <div className="title">{hit.name}</div>
        <div className="details">Email: {hit.email}</div>
       <div className="details">Website: {hit.website}</div>
      </div>

);

In this code - hits is used to display the name and email results that will be searched for.

Add the following code to the hit.style.css file:

@import url('https://fonts.googleapis.com/css?family=Quicksand&display=swap');

body{
    font-family: 'Quicksand', sans-serif;
    width: 100%;
    margin: 0;
}

.hit {
    background-color: rgb(216, 229, 227);
    border-radius: 5px;
}

  .title {
    color: grey;
    font-size: 20px;
    line-height: 3;
    text-align: center;
  }

  .details {
      color: grey;
      font-size: 10px;
      text-align: center;
  }

The App.js file should be updated using this code:

import React, { Component} from 'react';
import './App.css';
import {Search} from './../src/components/search/search.component';

class App extends Component {

    render(){
    return (
      <div className="App">
          <p>Random contact card</p>
          <Search />
    </div>
    );
    }
  }


  export default App;

The search component is imported and rendered.