Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/cristopher1/generator-koa2-api-generator

Yeoman generator to create a base structure for APIs based in koa2 framework, using tools such as: eslint, prettier, swagger and others.
https://github.com/cristopher1/generator-koa2-api-generator

api docker docker-compose es6 generator koa2 swagger yeoman yeoman-generator

Last synced: about 1 month ago
JSON representation

Yeoman generator to create a base structure for APIs based in koa2 framework, using tools such as: eslint, prettier, swagger and others.

Host: GitHub
URL: https://github.com/cristopher1/generator-koa2-api-generator
Owner: cristopher1
License: mit
Created: 2024-03-21T14:32:47.000Z (10 months ago)
Default Branch: main
Last Pushed: 2024-04-07T23:49:42.000Z (9 months ago)
Last Synced: 2024-10-16T19:12:32.421Z (3 months ago)
Topics: api, docker, docker-compose, es6, generator, koa2, swagger, yeoman, yeoman-generator
Language: JavaScript
Homepage: https://www.npmjs.com/package/generator-koa2-api-generator
Size: 757 KB
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

Welcome to generator-koa2-api-generator 👋

> Yeoman generator to create a base structure for APIs based in koa2 framework, using tools such as: eslint, prettier, swagger and others

### What's changed? See [generator-koa2-api-generator releases](https://github.com/cristopher1/generator-koa2-api-generator/releases)

### 🏠 [Homepage](https://github.com/cristopher1/generator-koa2-api-generator)

This generator was created using [generator-esmodules-generator](https://www.npmjs.com/package/generator-esmodules-generator) version 1.0.1

Includes configuration for development environment

Example of a generator created by `generator-koa2-api-generator`:

![generator-koa2-api-generator-project](https://github.com/cristopher1/generator-koa2-api-generator/assets/21159930/0b1a0512-b342-43da-94ef-9705d329a590)

### [Index](#index)

- [Installation](#installation)
- [Prerequisites](#prerequisites)
- [Arguments and options](#arguments-and-options)
- [Project structure](#structure)
- [Generators included](#generators-included)
- [The question: Do you want to automatically run the scripts that configure the package, then installing the dependencies?](#configuring-the-project-automatically)
- [The scripts in package.json](#scripts)
- [Getting To Know Yeoman](#know-yeoman)
- [Author](#author)
- [Contributing](#contributing)
- [Show your support](#support)
- [License](#license)

## Installation

First, install [Yeoman](http://yeoman.io) and generator-koa2-api-generator using [npm](https://www.npmjs.com/) (we assume you have pre-installed [node.js](https://nodejs.org/)).

```bash
npm install -g yo
npm install -g generator-koa2-api-generator
```

Then generate your new project:

```bash
yo koa2-api-generator project_name
```

## Prerequisites

First, you must create a folder, then you enter it using the terminal. Finally you runs.

```bash
yo koa2-api-generator project_name
```

Example:

```console
PS C:\Users\...\new_koa2_api_project> yo koa2-api-generator project_name
```

## Arguments and options

The generator-koa2-api-generator include two arguments called **projectName** and **databaseDriver** (postgresql or mysql, or mariadb). **projectName** is a required argument:

For example: If you want to create a new koa2 api called koa2_api_project (projectName = koa2_api_project) with postgresql plugin, you should use:

```bash
yo koa2-api-generator koa2_api_project postgresql
```

The generator-koa2-api-generator include various options, these are:

## Project structure

The project generated by generator-koa2-api-generator includes:

**Default project structure**

- **api (folder)**: In this folder there are project configurations and the src folder that contains the source code

- **.husky (folder)**: Contains git hook used by husky
- **.env (file)**: Contains the API environment variables.
- **.env.example (file)**: Contains an example of API environment variables used to create a .env file.
- **.eslintignore (file)**: Files and folders ignored by eslint.
- **.eslintrc.yml (file)**: Configuration used by eslint.
- **.gitignore (file)**: Files ignored by git.
- **.lintstagedrc.json (file)**: Configuration used by lintstaged.
- **.prettierignore (file)**: Files and folders ignored by prettier.
- **.prettierrc.json (file)**: Configuration used by prettier.
- **.sequelizerc (file)**: Configuration used by sequelize-cli.
- **api-specification (file)**: Contains specification used by openapi-comment-parser.
- **babel.config.json (file)**: Configuration used by babel. In this case babel-register (.sequelizerc).
- **commitlint.config.js (file)**: Congiguration used by commitlint.
- **package.json (file)**: Contains dependencies, dev dependencies, scripts, etc.
- **README.md (file)**: Documentation generated by generator-koa2-api-generator.
- **src (folder)**: Contains the source code:
- **config (folder)**: Contains configuration files, for example database.js (contains environment varibles used by sequelize), jwt.js (contains environment variables used by jsonwebtoken) and openapi.js (contains the configuration used by openapi-comment-parser).
- **db (folder)**: Contains folders used by sequelize.
- **migrations (folder)**: This folder contains CommonJS Modules (files with extension .cjs and use require/module.exports). Includes a default user migration.
- **models (folder)**: This folder contains ES Modules (by default the project generated by generator-koa2-api-generator uses ES Modules, files with extension .js and use import/export). Includes a default user model.
The index.js file loads the models exporting the orm constant.
- **seeders (folder)**: This folder contains CommonJS Modules (files with extension .cjs and use require/module.exports).
- **routes (folder)**: Contains the koa routers used by the project.
- **authentication (folder)**: Contains functions and routers to authenticate the users with json web token.
- **swagger (folder)**: Contains functions and routes to create documentation using swagger.
- **user (folder)**: Contains functions and routes to register, obtain and modify an user. Uses default model user
- **index.js (file)**: Contains the main koa2 router with prefix 'api/v1' and mounts the others routers.
- **schemas (folder)**: Contains openapi schemas and json schemas.
- **json (folder)**: Contains json schemas.
- **index.js**: Loads the json schemas using ajv, ajv-errors and ajv-formats. Exports the jsonSchema constant and the simpleJsonSchemaValidation function, the json schemas file should have the file name : 'name_of_json_schema.json' and they can be saved in subfolders within the json folder.
- **openapi (folder)**: Contains openapi schemas. The files in this folder have the .yml extension and they can have any name, for example: 'my_new_openapi_schema.yml'.
- **default_response (folder)**: Contains openapi schemas for koa2 default response (200, 201, 401, 404, 500).
- **json_web_token (folder)**: Contains openapi schemas for token (json web token) and create token.
- **secutiry (folder)**: Contains openapi schema for authentication with bearer token.
- **user (folder)**: Contains openapi schema for user.
- **types.d.ts (file)**: Includes any types used by the project, for example type Orm, JsonSchema, Module augmentation (Koa), etc. You can call the Orm/JsonSchema/others type using jsdoc, for example: /\*_ @type {import('route/to/typesfolder/types.d.ts').Orm} _/
- **api.js (file)**: Creates and configures the Koa object and it exports the Koa object.
- **server.js (file)**: Mounts the API and runs the server.

- If you do not want to use openapi.
- Delete the api/src/schemas/openapi folder.
- Delete the api/src/config/openapi.js file.
- Delete the api/src/routes/swagger folder.
- In the api/src/routes/index.js file, delete:
```node
if (environment !== 'production') {
router.use('/docs', swaggerRouter.routes())
}
```
- In terminal use:
```sh
cd api
npm uninstall openapi-comment-parser
```
- delete api-specification.yml
- Remove the openapi comment in the files in api/src/routes, for example:
```node
/**
* GET /api/v1/users/{userEmail}
*
* @tag API endpoints
* @security BearerAuth
* @summary Get an user by email
* @pathParam {string} userEmail
* @response 200 - Ok
* @responseContent {User} 200.application/json
* @response 401 - Unauthorized
* @responseComponent {Unauthorized} 401
* @response 404 - Not found
* @responseComponent {NotFound} 404
* @response 500 - Internal Server Error
* @responseComponent {InternalServerError} 500
*/
router.get('/:userEmail', async (ctx) => {
```
This comment begin with GET, POST, PUT or others HTTP Verb.
- If you do not want to use JSON Schemas.
- Delete the api/src/schemas/json folder.
- In terminal use:
```sh
cd api
npm uninstall ajv ajv-errors ajv-formats globs
```
- Delete in files api/src/routes/user/registerRouter.js, api/src/routes/user/router.js and api/src/routes/authentication/tokenRouter.js
```node
import { simpleJsonSchemaValidation } from '../../schemas/json/index.js'
```

**Added docker support**:

When the Docker support is activate (--useDocker is used), the following files are added to default project in api folder:

- **.dockerignore (file)**: Files and folders ignore to Docker.
- **Dockerfile (file)**: Used to create a docker image.
- **docker-entrypoint.sh (file)**: Contains scripts to run migrations in development mode. Used by ENTRYPOINT in Dockerfile.
- **wait-for-it.sh (file)**: More information, see [wait-for-it.sh in github](https://github.com/vishnubob/wait-for-it). Script used to wait for the database to be enabled to receive connections.

**Added docker compose support**:

When the Docker Compose support is activate (--useDockerCompose is used), the following files and folders are added to default.

- **api/.env (file)**: Adds the values corresponding to the database environment variables, for example for postgresql, adds the following environment variables:

```
DB_USERNAME=admin
DB_PASSWORD=admin
DB_NAME=api
DB_HOST=database
DB_PORT=5432
DB_DIALECT=postgres

DATABASE_URL=postgresql://admin:admin@database:5432/api
```

- **database (folder)**: Contains files used to create and cofigure the database.

- **.dockerignore (file)**: Files and folders ignored by docker.
- **.env (file)**: Environment variables used the database in docker.
- **.env.example (file)**: Contains an example of database environment variables used to create a .env file.
- **Dockerfile (file)**: Used to create docker image.

- **In the root folder**:
- **docker-compose.yml (file)**: Used to deploy the docker container (API and database), contains the volumen and environment variables used by the API and database, publish the API ports, etc.
- **.env (file)**: Contains the environment variables to configure docker-compose.yml file.
- **.env.example (file)**: Contains an example of docker-compose.yml environment variables used to create a .env file.

## Generators included

The generators included are:

`koa2-api-generator:app` used by `yo koa2-api-generator`: It is the generator used by default.

`koa2-api-generator:docker`: It is used to add support for Docker. It accepts the options `--useDocker`, `--nodeVersion` and `--projectFolderName`.

`koa2-api-generator:docker_compose`: It is used to add support for Docker Compose. It accepts the options `--useDockerCompose` and `--databaseName`.

## The question: Do you want to automatically run the scripts that configure the package, then installing the dependencies?

When you selects the true value, the following scripts ubicated in the package.json are executed:

- `init`
- `format:fix`

If you selects the false value, if you want to use husky, you must run `npm run init`.

## The scripts in package.json

The more important scripts added into the package.json created by this generator are:

- `"init"`: Runs the commands necessary to initialize the package, for example `init:husky`.
- `"dev"`: Runs the application in development mode using nodemon and dotenv.
- `"start"`: Runs the application using node.
- `"format"`: Checks the format using prettier.
- `"format:fix"`: Fixes the format using prettier.
- `"lint"`: static code analysis using eslint.
- `"lint:fix"`: Fixes the code using eslint.
- `"commitlint"`: Runs commitlint. It is used into .husky/commit-msg file. It is called by the commit-msg hook. See [git hook](https://www.atlassian.com/git/tutorials/git-hooks#:~:text=The%20commit%2Dmsg%20hook%20is,file%20that%20contains%20the%20message.).
- `"lint-staged"`: Runs lint-staged. It is used into .husky/pre-commit file. It is called by the pre-commit hook. See [git hook](https://www.atlassian.com/git/tutorials/git-hooks#:~:text=The%20commit%2Dmsg%20hook%20is,file%20that%20contains%20the%20message.).
- `"quality-check"`: Runs `npm run format && npm run lint`. It is used into .husky/pre-push file. It is called by the pre-push hook See [git hook](https://www.atlassian.com/git/tutorials/git-hooks#:~:text=The%20commit%2Dmsg%20hook%20is,file%20that%20contains%20the%20message.).

## Getting To Know Yeoman

- Yeoman has a heart of gold.
- Yeoman is a person with feelings and opinions, but is very easy to work with.
- Yeoman can be too opinionated at times but is easily convinced not to be.
- Feel free to [learn more about Yeoman](http://yeoman.io/).

## Author Author

👤 **Cristopher Jiménez Meza**

- Github: [@cristopher1](https://github.com/cristopher1)

## 🤝 Contributing

Contributions, issues and feature requests are welcome!
Feel free to check [issues page](https://github.com/cristopher1/generator-koa2-api-generator/issues). You can also take a look at the [contributing guide](https://github.com/cristopher1/generator-koa2-api-generator/blob/master/CONTRIBUTING.md).

## Show your support

Give a ⭐️ if this project helped you!

## 📝 License

---