generator-koa2-api-generator
v1.0.2
Published
Yeoman generator to create a base structure for APIs based in koa2 framework and sequelize, using tools such as: eslint, prettier, swagger and others
Downloads
2
Maintainers
Readme
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
🏠 Homepage
This generator was created using generator-esmodules-generator version 1.0.1
Includes configuration for development environment
Example of a generator created by generator-koa2-api-generator
:
Index
- Installation
- Prerequisites
- Arguments and options
- Project structure
- Generators included
- The question: Do you want to automatically run the scripts that configure the package, then installing the dependencies?
- The scripts in package.json
- Getting To Know Yeoman
- Author
- Contributing
- Show your support
- License
Installation
First, install Yeoman and generator-koa2-api-generator using npm (we assume you have pre-installed node.js).
npm install -g yo
npm install -g generator-koa2-api-generator
Then generate your new project:
yo koa2-api-generator project_name
Prerequisites
First, you must create a folder, then you enter it using the terminal. Finally you runs.
yo koa2-api-generator project_name
Example:
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:
yo koa2-api-generator koa2_api_project postgresql
The generator-koa2-api-generator include various options, these are:
| option | value | default | description | example |
| :---------------- | :-----: | :-----: | :------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------- |
| runGitInit | Boolean | false | Run git init automatically, then installing the dependencies | yo koa2-api-generator project_name --runGitInit
|
| runPackageScripts | Boolean | false | Run the scripts that configure the package, then installing the dependencies | yo koa2-api-generator project_name --runPackageScripts
|
| useDocker | Boolean | false | Add docker support using DockerFile, .dockerignore and others | yo koa2-api-generator project_name --useDocker
|
| nodeVersion | Number | 16 | Node version used in DockerFile. (FROM nodeVersion). Recommended to use node 16, 18, 20 or 21 | yo koa2-api-generator project_name --nodeVersion=21
|
| projectFolderName | String | api | Project folder name used in DockerFile. (WORKDIR /usr/src/projectFolderName) | yo koa2-api-generator project_name --projectFolderName=project_folder_name
|
| useDockerCompose | String | false | Add Docker Compose support. | yo koa2-api-generator project_name --useDockerCompose
|
| databaseName | String | null | Select the database to which the application will connect. Accepts the values: postgresql, mysql and mariadb. | yo koa2-api-generator project_name --databaseName=postgresql
|
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.
- json (folder): Contains json schemas.
- 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:
if (environment !== 'production') { router.use('/docs', swaggerRouter.routes()) }
- In terminal use:
cd api npm uninstall openapi-comment-parser
- delete api-specification.yml
- Remove the openapi comment in the files in api/src/routes, for example:
This comment begin with GET, POST, PUT or others HTTP Verb./** * 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) => {
If you do not want to use JSON Schemas.
- Delete the api/src/schemas/json folder.
- In terminal use:
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
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. 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 exampleinit: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."lint-staged"
: Runs lint-staged. It is used into .husky/pre-commit file. It is called by the pre-commit hook. See git hook."quality-check"
: Runsnpm run format && npm run lint
. It is used into .husky/pre-push file. It is called by the pre-push hook See git hook.
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.
Author Author
👤 Cristopher Jiménez Meza
- Github: @cristopher1
🤝 Contributing
Contributions, issues and feature requests are welcome!Feel free to check issues page. You can also take a look at the contributing guide.
Show your support
Give a ⭐️ if this project helped you!
📝 License
Copyright © 2024 Cristopher Jiménez Meza. This project is MIT licensed.