express-sequelize-adminjs-swagger

Awesome REST API boilerplate with documentation, admin panel and dev tools

Prerequisites

Before you begin, ensure that you have the following prerequisites installed on your system :

• Node.js
• Docker

Installation

1. Clone the repository :

git clone https://github.com/AlexandrePereon/express-sequelize-adminjs-swagger.git

2. Navigate to the project directory :

cd express-sequelize-adminjs-swagger

3. Install the dependencies :

npm install

Setup .env File

To configure your project, you'll need to set up the .env file. Start by creating a copy of the environment variables file :

cp local.env .env

Open the newly created .env file and fill in the necessary values for the following variables:

#EXPRESS
API_PORT=3000
API_HOST=localhost

#ENVIRONMENT
NODE_ENV=development

#JWT
JWT_SECRET=jwt-key
JWT_TIMEOUT=1h

#DATABASE
DB_DIALECT=mysql
DB_HOST=localhost
DB_USER=root
DB_PASS=password
DB_NAME=Base_Test
DB_PORT=3306

Development

Before starting development, ensure that a MySQL server is running. If you don't have one, you can quickly set up a test MySQL server using Docker :

docker run --name test-mysql -e MYSQL_ROOT_PASSWORD='DB_PASS' -p 3306:3306 -d mysql:8.0-debian

Replace 'DB_PASS' with the password specified in your .env configuration file.

Now, let's set up the database :

1. Create the database:

   npm run db:create

2. Run the database migrations :

   npm run db:migrate

3. Set up the admin and test user :

   npm run db:seed:all

Now, you're ready to start the development server :

npm run dev

Remember to check the terminal for any additional information or error messages.

Deployment

Local Deployment

Ensure that the MySQL server is running with your database created.

1. Build the application :

npm run build

2. Start the server :

npm run start

With Docker Compose

This deployment includes a MySQL database! Make sure to build the API as shown above before proceeding.

1. Build Docker images :

docker-compose build

2. Start the application using Docker Compose :

docker compose up -d

Admin Panel and Documentation

Admin Panel Access

Admin Panel URL : http://localhost:3000/admin

Example Image :

Modification Location :

To modify the content of the Admin Panel, navigate to the src/adminjs folder. These modifications involve adjusting AdminJS configurations, defining models, and customizing the appearance and behavior of the admin interface.

API Documentation Access

Swagger Documentation URL : http://localhost:3000/api-docs

Example Image :

Modification Location :

To update or modify the API documentation, you can make changes directly to your API routes routes.ts. The documentation is generated based on comments using Swagger. Adjust comments and annotations to enhance and customize the documentation.

Development Tools

To enhance your development experience, we recommend using the following Visual Studio Code extensions :

• ESLint
• Prettier - Code formatter
• Docker
• GitLens - Git supercharged

The project includes several npm scripts for various tasks. Here is a brief description of each command:

• db:create : Create the database using Sequelize CLI.
• db:migrate : Run database migrations to apply changes to the database schema.
• db:seed:all : Seed the database with predefined data.
• db:seed:undo:all : Undo all database seeding.
• db:seed:admin : Seed the database with an admin user.
• db:drop : Drop the entire database.
• test : Run tests for the API endpoint.
• dev: Start the development server using ts-node-dev.
• build : Compile TypeScript source files into JavaScript.
• start : Start the server using the compiled JavaScript files in the dist directory.