{"id":15097827,"url":"https://github.com/cristopher1/generator-koa2-api-generator","last_synced_at":"2026-01-06T10:55:19.110Z","repository":{"id":230307461,"uuid":"775514583","full_name":"cristopher1/generator-koa2-api-generator","owner":"cristopher1","description":"Yeoman generator to create a base structure for APIs based in koa2 framework, using tools such as: eslint, prettier, swagger and others.","archived":false,"fork":false,"pushed_at":"2024-04-07T23:49:42.000Z","size":775,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-01T17:44:40.971Z","etag":null,"topics":["api","docker","docker-compose","es6","generator","koa2","swagger","yeoman","yeoman-generator"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/generator-koa2-api-generator","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cristopher1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-21T14:32:47.000Z","updated_at":"2024-04-06T01:01:48.000Z","dependencies_parsed_at":"2024-04-08T00:32:03.627Z","dependency_job_id":null,"html_url":"https://github.com/cristopher1/generator-koa2-api-generator","commit_stats":{"total_commits":130,"total_committers":1,"mean_commits":130.0,"dds":0.0,"last_synced_commit":"d2eaec58016c1dc57d0b365c5e51c2f986d49aa2"},"previous_names":["cristopher1/generator-koa2-api-generator"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cristopher1%2Fgenerator-koa2-api-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cristopher1%2Fgenerator-koa2-api-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cristopher1%2Fgenerator-koa2-api-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cristopher1%2Fgenerator-koa2-api-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cristopher1","download_url":"https://codeload.github.com/cristopher1/generator-koa2-api-generator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245854302,"owners_count":20683332,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","docker","docker-compose","es6","generator","koa2","swagger","yeoman","yeoman-generator"],"created_at":"2024-09-25T16:40:45.156Z","updated_at":"2026-01-06T10:55:19.048Z","avatar_url":"https://github.com/cristopher1.png","language":"JavaScript","readme":"\u003ch1 align=\"center\"\u003eWelcome to generator-koa2-api-generator 👋\u003c/h1\u003e\n\u003cp\u003e\n  \u003cimg alt=\"Version\" src=\"https://img.shields.io/badge/version-1.0.2-blue.svg?cacheSeconds=2592000\" /\u003e\n  \u003ca href=\"https://github.com/cristopher1/generator-koa2-api-generator#readme\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Documentation\" src=\"https://img.shields.io/badge/documentation-yes-brightgreen.svg\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/cristopher1/generator-koa2-api-generator/graphs/commit-activity\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Maintenance\" src=\"https://img.shields.io/badge/Maintained%3F-yes-green.svg\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/cristopher1/generator-koa2-api-generator/blob/master/LICENSE\" target=\"_blank\"\u003e\n    \u003cimg alt=\"License: MIT\" src=\"https://img.shields.io/github/license/cristopher1/generator-koa2-api-generator\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003e Yeoman generator to create a base structure for APIs based in koa2 framework, using tools such as: eslint, prettier, swagger and others\n\n### What's changed? See [generator-koa2-api-generator releases](https://github.com/cristopher1/generator-koa2-api-generator/releases)\n\n### 🏠 [Homepage](https://github.com/cristopher1/generator-koa2-api-generator)\n\nThis generator was created using [generator-esmodules-generator](https://www.npmjs.com/package/generator-esmodules-generator) version 1.0.1\n\nIncludes configuration for development environment\n\nExample of a generator created by `generator-koa2-api-generator`:\n\n![generator-koa2-api-generator-project](https://github.com/cristopher1/generator-koa2-api-generator/assets/21159930/0b1a0512-b342-43da-94ef-9705d329a590)\n\n### [Index](#index)\n\n- [Installation](#installation)\n- [Prerequisites](#prerequisites)\n- [Arguments and options](#arguments-and-options)\n- [Project structure](#structure)\n- [Generators included](#generators-included)\n- [The question: Do you want to automatically run the scripts that configure the package, then installing the dependencies?](#configuring-the-project-automatically)\n- [The scripts in package.json](#scripts)\n- [Getting To Know Yeoman](#know-yeoman)\n- [Author](#author)\n- [Contributing](#contributing)\n- [Show your support](#support)\n- [License](#license)\n\n## \u003ca id=\"installation\"\u003e\u003c/a\u003e Installation\n\nFirst, 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/)).\n\n```bash\nnpm install -g yo\nnpm install -g generator-koa2-api-generator\n```\n\nThen generate your new project:\n\n```bash\nyo koa2-api-generator project_name\n```\n\n## \u003ca id=\"prerequisites\"\u003e\u003c/a\u003e Prerequisites\n\nFirst, you must create a folder, then you enter it using the terminal. Finally you runs.\n\n```bash\nyo koa2-api-generator project_name\n```\n\nExample:\n\n```console\nPS C:\\Users\\...\\new_koa2_api_project\u003e yo koa2-api-generator project_name\n```\n\n## \u003ca id=\"arguments-and-options\"\u003e\u003c/a\u003e Arguments and options\n\nThe generator-koa2-api-generator include two arguments called **projectName** and **databaseDriver** (postgresql or mysql, or mariadb). **projectName** is a required argument:\n\nFor example: If you want to create a new koa2 api called koa2_api_project (projectName = koa2_api_project) with postgresql plugin, you should use:\n\n```bash\nyo koa2-api-generator koa2_api_project postgresql\n```\n\nThe generator-koa2-api-generator include various options, these are:\n\n| option            |  value  | default | description                                                                                                   | example                                                                      |\n| :---------------- | :-----: | :-----: | :------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------- |\n| runGitInit        | Boolean |  false  | Run git init automatically, then installing the dependencies                                                  | `yo koa2-api-generator project_name --runGitInit`                            |\n| runPackageScripts | Boolean |  false  | Run the scripts that configure the package, then installing the dependencies                                  | `yo koa2-api-generator project_name --runPackageScripts`                     |\n| useDocker         | Boolean |  false  | Add docker support using DockerFile, .dockerignore and others                                                 | `yo koa2-api-generator project_name --useDocker`                             |\n| 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`                        |\n| projectFolderName | String  |   api   | Project folder name used in DockerFile. (WORKDIR /usr/src/projectFolderName)                                  | `yo koa2-api-generator project_name --projectFolderName=project_folder_name` |\n| useDockerCompose  | String  |  false  | Add Docker Compose support.                                                                                   | `yo koa2-api-generator project_name --useDockerCompose`                      |\n| 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`               |\n\n## \u003ca id=\"structure\"\u003e\u003c/a\u003e Project structure\n\nThe project generated by generator-koa2-api-generator includes:\n\n**Default project structure**\n\n- **api (folder)**: In this folder there are project configurations and the src folder that contains the source code\n\n  - **.husky (folder)**: Contains git hook used by husky\n  - **.env (file)**: Contains the API environment variables.\n  - **.env.example (file)**: Contains an example of API environment variables used to create a .env file.\n  - **.eslintignore (file)**: Files and folders ignored by eslint.\n  - **.eslintrc.yml (file)**: Configuration used by eslint.\n  - **.gitignore (file)**: Files ignored by git.\n  - **.lintstagedrc.json (file)**: Configuration used by lintstaged.\n  - **.prettierignore (file)**: Files and folders ignored by prettier.\n  - **.prettierrc.json (file)**: Configuration used by prettier.\n  - **.sequelizerc (file)**: Configuration used by sequelize-cli.\n  - **api-specification (file)**: Contains specification used by openapi-comment-parser.\n  - **babel.config.json (file)**: Configuration used by babel. In this case babel-register (.sequelizerc).\n  - **commitlint.config.js (file)**: Congiguration used by commitlint.\n  - **package.json (file)**: Contains dependencies, dev dependencies, scripts, etc.\n  - **README.md (file)**: Documentation generated by generator-koa2-api-generator.\n  - **src (folder)**: Contains the source code:\n    - **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).\n    - **db (folder)**: Contains folders used by sequelize.\n      - **migrations (folder)**: This folder contains CommonJS Modules (files with extension .cjs and use require/module.exports). Includes a default user migration.\n      - **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.\n        The index.js file loads the models exporting the orm constant.\n      - **seeders (folder)**: This folder contains CommonJS Modules (files with extension .cjs and use require/module.exports).\n    - **routes (folder)**: Contains the koa routers used by the project.\n      - **authentication (folder)**: Contains functions and routers to authenticate the users with json web token.\n      - **swagger (folder)**: Contains functions and routes to create documentation using swagger.\n      - **user (folder)**: Contains functions and routes to register, obtain and modify an user. Uses default model user\n      - **index.js (file)**: Contains the main koa2 router with prefix 'api/v1' and mounts the others routers.\n    - **schemas (folder)**: Contains openapi schemas and json schemas.\n      - **json (folder)**: Contains json schemas.\n        - **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.\n      - **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'.\n        - **default_response (folder)**: Contains openapi schemas for koa2 default response (200, 201, 401, 404, 500).\n        - **json_web_token (folder)**: Contains openapi schemas for token (json web token) and create token.\n        - **secutiry (folder)**: Contains openapi schema for authentication with bearer token.\n        - **user (folder)**: Contains openapi schema for user.\n    - **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} _/\n    - **api.js (file)**: Creates and configures the Koa object and it exports the Koa object.\n    - **server.js (file)**: Mounts the API and runs the server.\n\n- If you do not want to use openapi.\n  - Delete the api/src/schemas/openapi folder.\n  - Delete the api/src/config/openapi.js file.\n  - Delete the api/src/routes/swagger folder.\n  - In the api/src/routes/index.js file, delete:\n    ```node\n    if (environment !== 'production') {\n      router.use('/docs', swaggerRouter.routes())\n    }\n    ```\n  - In terminal use:\n    ```sh\n      cd api\n      npm uninstall openapi-comment-parser\n    ```\n  - delete api-specification.yml\n  - Remove the openapi comment in the files in api/src/routes, for example:\n    ```node\n      /**\n        * GET /api/v1/users/{userEmail}\n        *\n        * @tag API endpoints\n        * @security BearerAuth\n        * @summary Get an user by email\n        * @pathParam {string} userEmail\n        * @response 200 - Ok\n        * @responseContent {User} 200.application/json\n        * @response 401 - Unauthorized\n        * @responseComponent {Unauthorized} 401\n        * @response 404 - Not found\n        * @responseComponent {NotFound} 404\n        * @response 500 - Internal Server Error\n        * @responseComponent {InternalServerError} 500\n      */\n      router.get('/:userEmail', async (ctx) =\u003e {\n    ```\n    This comment begin with GET, POST, PUT or others HTTP Verb.\n- If you do not want to use JSON Schemas.\n  - Delete the api/src/schemas/json folder.\n  - In terminal use:\n    ```sh\n      cd api\n      npm uninstall ajv ajv-errors ajv-formats globs\n    ```\n  - Delete in files api/src/routes/user/registerRouter.js, api/src/routes/user/router.js and api/src/routes/authentication/tokenRouter.js\n    ```node\n    import { simpleJsonSchemaValidation } from '../../schemas/json/index.js'\n    ```\n\n**Added docker support**:\n\nWhen the Docker support is activate (--useDocker is used), the following files are added to default project in api folder:\n\n- **.dockerignore (file)**: Files and folders ignore to Docker.\n- **Dockerfile (file)**: Used to create a docker image.\n- **docker-entrypoint.sh (file)**: Contains scripts to run migrations in development mode. Used by ENTRYPOINT in Dockerfile.\n- **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.\n\n**Added docker compose support**:\n\nWhen the Docker Compose support is activate (--useDockerCompose is used), the following files and folders are added to default.\n\n- **api/.env (file)**: Adds the values ​​corresponding to the database environment variables, for example for postgresql, adds the following environment variables:\n\n```\n  DB_USERNAME=admin\n  DB_PASSWORD=admin\n  DB_NAME=api\n  DB_HOST=database\n  DB_PORT=5432\n  DB_DIALECT=postgres\n\n  DATABASE_URL=postgresql://admin:admin@database:5432/api\n```\n\n- **database (folder)**: Contains files used to create and cofigure the database.\n\n  - **.dockerignore (file)**: Files and folders ignored by docker.\n  - **.env (file)**: Environment variables used the database in docker.\n  - **.env.example (file)**: Contains an example of database environment variables used to create a .env file.\n  - **Dockerfile (file)**: Used to create docker image.\n\n- **In the root folder**:\n  - **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.\n  - **.env (file)**: Contains the environment variables to configure docker-compose.yml file.\n  - **.env.example (file)**: Contains an example of docker-compose.yml environment variables used to create a .env file.\n\n## \u003ca id=\"generators-included\"\u003e\u003c/a\u003e Generators included\n\nThe generators included are:\n\n`koa2-api-generator:app` used by `yo koa2-api-generator`: It is the generator used by default.\n\n`koa2-api-generator:docker`: It is used to add support for Docker. It accepts the options `--useDocker`, `--nodeVersion` and `--projectFolderName`.\n\n`koa2-api-generator:docker_compose`: It is used to add support for Docker Compose. It accepts the options `--useDockerCompose` and `--databaseName`.\n\n## \u003ca id=\"configuring-the-project-automatically\"\u003e\u003c/a\u003e The question: Do you want to automatically run the scripts that configure the package, then installing the dependencies?\n\nWhen you selects the true value, the following scripts ubicated in the package.json are executed:\n\n- `init`\n- `format:fix`\n\nIf you selects the false value, if you want to use husky, you must run `npm run init`.\n\n## \u003ca id=\"scripts\"\u003e\u003c/a\u003e The scripts in package.json\n\nThe more important scripts added into the package.json created by this generator are:\n\n- `\"init\"`: Runs the commands necessary to initialize the package, for example `init:husky`.\n- `\"dev\"`: Runs the application in development mode using nodemon and dotenv.\n- `\"start\"`: Runs the application using node.\n- `\"format\"`: Checks the format using prettier.\n- `\"format:fix\"`: Fixes the format using prettier.\n- `\"lint\"`: static code analysis using eslint.\n- `\"lint:fix\"`: Fixes the code using eslint.\n- `\"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.).\n- `\"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.).\n- `\"quality-check\"`: Runs `npm run format \u0026\u0026 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.).\n\n## \u003ca id=\"know-yeoman\"\u003e\u003c/a\u003e Getting To Know Yeoman\n\n- Yeoman has a heart of gold.\n- Yeoman is a person with feelings and opinions, but is very easy to work with.\n- Yeoman can be too opinionated at times but is easily convinced not to be.\n- Feel free to [learn more about Yeoman](http://yeoman.io/).\n\n## \u003ca id=\"author\"\u003e\u003c/a\u003e Author Author\n\n👤 **Cristopher Jiménez Meza**\n\n- Github: [@cristopher1](https://github.com/cristopher1)\n\n## \u003ca id=\"contributing\"\u003e\u003c/a\u003e 🤝 Contributing\n\nContributions, issues and feature requests are welcome!\u003cbr /\u003eFeel 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).\n\n## \u003ca id=\"support\"\u003e\u003c/a\u003e Show your support\n\nGive a ⭐️ if this project helped you!\n\n## \u003ca id=\"license\"\u003e\u003c/a\u003e 📝 License\n\nCopyright © 2024 [Cristopher Jiménez Meza](https://github.com/cristopher1).\u003cbr /\u003e\nThis project is [MIT](https://github.com/cristopher1/generator-koa2-api-generator/blob/master/LICENSE) licensed.\n\n---\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcristopher1%2Fgenerator-koa2-api-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcristopher1%2Fgenerator-koa2-api-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcristopher1%2Fgenerator-koa2-api-generator/lists"}