{"id":16052163,"url":"https://github.com/xutyxd/ts-openapi-contract-first-boilerplate","last_synced_at":"2026-02-05T06:31:06.957Z","repository":{"id":257815678,"uuid":"869188677","full_name":"xutyxd/ts-openapi-contract-first-boilerplate","owner":"xutyxd","description":"A boilerplate for building contract-first APIs in TypeScript with OpenAPI. Includes OpenAPI definition, compliant server setup, and npm package generation for seamless API development.","archived":false,"fork":false,"pushed_at":"2024-11-18T20:40:39.000Z","size":223,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-16T18:00:03.392Z","etag":null,"topics":["api","api-contract","api-design","api-server","boilerplate","contract-first","node","nodejs","npm","npm-package","openapi","rest","scafolding","typescript","typescript-starter","typescript-starter-template","typescript-template"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xutyxd.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,"zenodo":null}},"created_at":"2024-10-07T21:41:28.000Z","updated_at":"2024-11-18T20:40:43.000Z","dependencies_parsed_at":null,"dependency_job_id":"127096a8-8077-4bb1-bef8-e32a8b50a861","html_url":"https://github.com/xutyxd/ts-openapi-contract-first-boilerplate","commit_stats":null,"previous_names":["xutyxd/ts-openapi-contract-first-boilerplate"],"tags_count":2,"template":true,"template_full_name":null,"purl":"pkg:github/xutyxd/ts-openapi-contract-first-boilerplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xutyxd%2Fts-openapi-contract-first-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xutyxd%2Fts-openapi-contract-first-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xutyxd%2Fts-openapi-contract-first-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xutyxd%2Fts-openapi-contract-first-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xutyxd","download_url":"https://codeload.github.com/xutyxd/ts-openapi-contract-first-boilerplate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xutyxd%2Fts-openapi-contract-first-boilerplate/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266160820,"owners_count":23885886,"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","api-contract","api-design","api-server","boilerplate","contract-first","node","nodejs","npm","npm-package","openapi","rest","scafolding","typescript","typescript-starter","typescript-starter-template","typescript-template"],"created_at":"2024-10-09T01:07:35.957Z","updated_at":"2026-02-05T06:31:06.951Z","avatar_url":"https://github.com/xutyxd.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/xutyxd/ts-openapi-contract-first-boilerplate\"\u003e\n    \u003cpicture\u003e\n      \u003csource srcset=\"./ts-contract-first-logo.png\" width=\"150\"\u003e\n      \u003cimg alt=\"TS Contract First logo\" src=\"./ts-contract-first-logo.png\" width=\"150\"\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n# Contract-First Boilerplate for TypeScript – Streamline Your API Development\n\nA boilerplate for building contract-first APIs in TypeScript with OpenAPI. Includes OpenAPI definition, compliant server setup, and npm package generation for seamless API development.\n\n\n## Quick Start Guide\n\n1. **Clone the repository:**\n   ```bash\n   git clone https://github.com/xutyxd/ts-openapi-contract-first-boilerplate\n   cd ts-openapi-contract-first-boilerplate\n\n2. **Install dependencies:**\n   ```bash\n   npm install\n   ```\n\n3. **Generate OpenAPI definition:**\n   ```bash\n   npm run openapi:bundle\n   npm run openapi:types\n   npm run openapi:docs\n   ```\n\n4. **Run the tests:**\n   ```bash\n   npm run test:ts\n   npm run test:units\n   npm run test:functionals\n   ```\n\n5. **Run the server:**\n   ```bash\n   npm run start:local\n   ```\n\n## Project Structure\n\n| Folder | Description |\n| ------ | ----------- |\n| **configurations** | Contains configuration files for the server and package |\n| **cucumber.js** | Cucumber configuration file |\n| **package** | Contains the package build configuration and scripts |\n| **public** | Contains the static files for the server |\n| **scripts** | Contains the scripts for the server and package |\n| **src** | Contains the source code for the server and package |\n| **src/openapi** | Contains the OpenAPI definition and specification |\n| **src/openapi/common** | Contains the common models and responses |\n| **src/openapi/crosscutting** | Contains the crosscutting models and responses |\n| **src/openapi/crosscutting/health-check** | Contains the health-check entity **example** |\n| **src/openapi/definition.json** | Contains the OpenAPI definition |\n| **src/package** | Contains the package source code |\n| **src/server** | Contains the server source code |\n| **src/server/app.ts** | Contains the server entry point |\n| **src/server/configuration** | Contains the server configuration |\n| **src/server/crosscutting** | Contains the crosscutting source code |\n| **src/server/crosscutting/common** | Contains the common source code |\n| **tests** | Contains the test files |\n| **tests/functionals** | Contains the functional tests |\n| **tests/units** | Contains the unit tests |\n\n### How to extend the project\n\n1. Define openapi request/responses for new entity\n   - Create the new folder scaffolding the entity\n       ```bash\n       mkdir src/openapi/new-entity\n       mkdir src/openapi/new-entity/examples\n       mkdir src/openapi/new-entity/models\n       mkdir src/openapi/new-entity/paths\n       mkdir src/openapi/new-entity/request\n       ```\n    - Add ref to paths in `definition.json`\n    - Optionally, add ref to components in definition.json\n\n2. Add tests for new entity\n    - Create the new folder scaffolding the entity\n        ```bash\n        mkdir tests/functionals/new-entity\n        mkdir tests/functionals/new-entity/new-entity.feature\n        mkdir tests/functionals/new-entity/new-entity.feature.steps.ts\n        ```\n\n        mkdir tests/units/new-entity\n\n3. Finally, add the new entity to the server\n    - Run next command to scaffold the entity\n        ```bash\n        npm run entity:scaffold new-entity\n        ```\n    - `src/server/app.ts` Add the new entity to the container\n\n## Dependencies\nCheck dependencies for more documentation\n- [Node.js](https://nodejs.org/en/) (v21.6.2)\n- [npm](https://www.npmjs.com/) (v9.6.1)\n- [SoE](https://github.com/xutyxd/server-over-express) (v1.6.1)\n- [InversifyJS](https://github.com/inversify/InversifyJS) (v6.0.2)\n- [OpenAPI Fetch](https://github.com/xutyxd/openapi-fetch) (v0.12.0)\n- [Ajv](https://github.com/ajv-validator/ajv) (v8.17.1)\n\n## License\n\nThis project is licensed under the AGPL-3.0 license - see the [LICENSE](LICENSE) file for details\n\n\u003cp align=\"left\"\u003e\n  Made with ☕ by\n  \u003ca href=\"https://github.com/xutyxd\"\u003e\n    XutyXD\n  \u003c/a\u003e\n\u003c/p\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxutyxd%2Fts-openapi-contract-first-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxutyxd%2Fts-openapi-contract-first-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxutyxd%2Fts-openapi-contract-first-boilerplate/lists"}