{"id":22221112,"url":"https://github.com/davesag/api-server-boilerplate","last_synced_at":"2025-07-27T16:31:05.778Z","repository":{"id":37072347,"uuid":"178339446","full_name":"davesag/api-server-boilerplate","owner":"davesag","description":"My own API Server Boilerplate codebase","archived":false,"fork":false,"pushed_at":"2024-09-18T09:54:24.000Z","size":1921,"stargazers_count":7,"open_issues_count":7,"forks_count":1,"subscribers_count":3,"default_branch":"develop","last_synced_at":"2024-09-18T13:10:54.360Z","etag":null,"topics":["api-boilerplate","api-server","boilerplate","boilerplate-api","express-js","swagger","swagger-api"],"latest_commit_sha":null,"homepage":"","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/davesag.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["davesag"]}},"created_at":"2019-03-29T05:39:22.000Z","updated_at":"2024-04-29T07:32:25.000Z","dependencies_parsed_at":"2023-12-24T04:24:25.239Z","dependency_job_id":"bcf20df2-c098-409d-b3f6-97cbe7708768","html_url":"https://github.com/davesag/api-server-boilerplate","commit_stats":null,"previous_names":[],"tags_count":24,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davesag%2Fapi-server-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davesag%2Fapi-server-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davesag%2Fapi-server-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davesag%2Fapi-server-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davesag","download_url":"https://codeload.github.com/davesag/api-server-boilerplate/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227817166,"owners_count":17824199,"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-boilerplate","api-server","boilerplate","boilerplate-api","express-js","swagger","swagger-api"],"created_at":"2024-12-02T23:12:18.744Z","updated_at":"2025-07-27T16:31:05.772Z","avatar_url":"https://github.com/davesag.png","language":"JavaScript","funding_links":["https://github.com/sponsors/davesag"],"categories":[],"sub_categories":[],"readme":"# api-server-boilerplate\n\nA stripped down API boilerplate built around NodeJS and OpenAPI (Swagger) V3.\n\n## ARCHIVED\n\nThis code is quite old now and does not support the very latest versions of Express.\n\nThere's not much need for it any longer so I am archiving it.\n\n## Configuration\n\nSet the following environment variables\n\n| Variable | Default | Notes                          |\n| -------- | ------- | ------------------------------ |\n| `PORT`   | `8282`  | The port the server listens on |\n\n## API Routes\n\nIf it's running locally (see below) point a browser at any of the following routes:\n\n- [localhost:8282](http://127.0.0.1:8282)\n- [localhost:8282/ping](http://127.0.0.1:8282/ping)\n- [localhost:8282/api/v1/hello/some name](http://127.0.0.1:8282/api/v1/hello/some%20name)\n- [localhost:8282/api/v1/snooze](http://127.0.0.1:8282/api/v1/snooze)\n\nand see the API docs at\n\n- [localhost:8282/docs](http://127.0.0.1:8282/docs)\n\n## What's the point of this?\n\nI used to write a lot of APIs and distilled my then best-practice into this codebase to save myself time, and as example code for other developers wondering how to do this sort of stuff.\n\n## What do you do with it?\n\nThis is a GitHub Template so either click the ['use this template'](https://github.com/davesag/api-server-boilerplate/generate) button above, or clone this rep, or fork it, nuke the existing `.git` data and replace with your own `git init` and `git flow init` edit the `README.md` file, add your own details to `api.yml` and add routes to `src/api/` as you like.\n\n## What's included?\n\n- a couple of root-level API routes and simple controllers\n\n  - `src/api/ping`\n  - `src/api/versions`\n\n- a versioned API route and controller\n\n  - `src/api/v1/hello`\n\n- example of an asynchronous route using [`route-async`](https://github.com/davesag/route-async)\n\n  - `src/api/v1/snooze`\n\n- automatic construction of api controller routes using [`traverse-folders`](https://github.com/davesag/traverse-folders)\n- automatic linking of swagger paths to controllers using [`swagger-routes-express`](https://github.com/davesag/swagger-routes-express)\n- request and response validation using [`express-openapi-validator`](https://github.com/cdimascio/express-openapi-validator)\n- automatic generation of API docs using [`swagger-ui-express`](https://github.com/scottie1984/swagger-ui-express)\n- simple logging (swap out the code in `src/utils/logger` to add your own)\n- standardised [`node-http-error`](https://github.com/carsondarling/node-http-error) and [`http-status-codes`](https://github.com/prettymuchbryce/http-status-codes) and simple `generic` and `notFound` error handlers\n- [`dotenv`](https://github.com/motdotla/dotenv) support\n- the swagger editor as an easy to invoke docker image\n- simple `project.toml` [buildpacks](https://buildpacks.io) config.\n\n### Code quality\n\n- unit testing using\n\n  - [`mocha`](https://mochajs.org),\n  - [`sinon`](https://sinonjs.org),\n  - [`chai`](https://www.chaijs.com), and\n  - [`proxyquire`](https://github.com/thlorenz/proxyquire)\n\n- `request` and `response` mocks using [`mock-req-res`](https://github.com/davesag/mock-req-res)\n- 100% unit test coverage using [`nyc`](https://github.com/istanbuljs/nyc)\n- integration testing using [`supertest`](https://github.com/visionmedia/supertest)\n- code quality using [`eslint`](https://eslint.org) and [`prettier`](https://prettier.io)\n- [`circleci`](https://circleci.com) integration\n- [`snyk`](https://snyk.io) integration\n\n## What's not included?\n\nI've paired this right back to the simplest, most generic API I could, so there's no\n\n- authentication (add `passport` and update `src/utils/makeApp` and add appropriate security blocks to `api.yml`)\n- rate limiting\n- middleware (roll your own and update `src/utils/makeApp`)\n- monitoring\n- sockets or event listeners\n- databases, search systems, etc\n\n## Development\n\n### Branches\n\n\u003c!-- prettier-ignore --\u003e\n| Branch | Tests | Code Coverage | Audit | Comments |\n| ------ | ----- | ------------- | ----- | -------- |\n| `develop` | [![CircleCI](https://circleci.com/gh/davesag/api-server-boilerplate/tree/develop.svg?style=svg)](https://circleci.com/gh/davesag/api-server-boilerplate/tree/develop) | [![codecov](https://codecov.io/gh/davesag/api-server-boilerplate/branch/develop/graph/badge.svg)](https://codecov.io/gh/davesag/api-server-boilerplate) | [![Vulnerabilities](https://snyk.io/test/github/davesag/api-server-boilerplate/develop/badge.svg)](https://snyk.io/test/github/davesag/api-server-boilerplate/develop) | Work in progress |\n| `main`  | [![CircleCI](https://circleci.com/gh/davesag/api-server-boilerplate/tree/main.svg?style=svg)](https://circleci.com/gh/davesag/api-server-boilerplate/tree/main) | [![codecov](https://codecov.io/gh/davesag/api-server-boilerplate/branch/main/graph/badge.svg)](https://codecov.io/gh/davesag/api-server-boilerplate) | [![Vulnerabilities](https://snyk.io/test/github/davesag/api-server-boilerplate/main/badge.svg)](https://snyk.io/test/github/davesag/api-server-boilerplate/main) | Latest Production Release |\n\n### Prerequisites\n\n- [NodeJS](htps://nodejs.org), I use [`nvm`](https://github.com/creationix/nvm) to manage Node versions — `brew install nvm`.\n- [Docker](https://www.docker.com) if you want to use the Swagger Editor, or you wish to use a `buildpack`. Use [Docker for Mac](https://docs.docker.com/docker-for-mac/), not the `homebrew` version.\n- [Pack](https://buildpacks.io) to use `buildpacks` — `brew install buildpacks/tap/pack`\n\n### To build and run locally\n\nClone this (or better yet, fork it then clone your fork)\n\n```sh\nnpm install\nnpm start\n```\n\nYou can then go to [localhost:8282/docs](http://127.0.0.1:8282/docs) to see the docs.\n\n### `.env` file\n\nYou can put environment variables in a `.env` file.\n\n### Buildpacks.\n\nYou can use an `heroku buildpack` as follows:\n\n```sh\npack build api-server-boilerplate --builder heroku/buildpacks:18\ndocker run api-server-boilerplate\n```\n\nOr tweak the `project.toml` file to use whatever buildpacks and environment variables you wish.\n\n### Development Helpers\n\n| Service        | Port   | Command           | Notes              |\n| -------------- | ------ | ----------------- | ------------------ |\n| Swagger Editor | `8080` | `npm run swagger` | The swagger editor |\n\nCopy and paste the `api.yml` file into the editor to edit it.\n\n### Testing\n\n- `npm test` to run the unit tests\n- `npm run test:server` will run the integration tests\n- `npm run lint` will lint it\n- `npm run prettier` will prettify it\n- `npm run test:unit:cov` will run the unit tests with code coverage\n\n## Contributing\n\nPlease see the [contributing notes](CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavesag%2Fapi-server-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavesag%2Fapi-server-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavesag%2Fapi-server-boilerplate/lists"}