{"id":26119267,"url":"https://github.com/aleksandryackovlev/openapi-mock-express-middleware","last_synced_at":"2025-04-13T10:34:22.695Z","repository":{"id":40290363,"uuid":"233542398","full_name":"aleksandryackovlev/openapi-mock-express-middleware","owner":"aleksandryackovlev","description":"Generates express mock-servers from OpenAPI specs","archived":false,"fork":false,"pushed_at":"2024-12-22T18:32:04.000Z","size":1242,"stargazers_count":28,"open_issues_count":2,"forks_count":11,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-10T16:17:00.731Z","etag":null,"topics":["codegen","express","middleware","mock","mock-server","openapi","swagger","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/aleksandryackovlev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","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":"2020-01-13T08:02:38.000Z","updated_at":"2025-01-15T15:04:52.000Z","dependencies_parsed_at":"2024-04-24T20:32:36.055Z","dependency_job_id":"55f1810c-43b3-4313-bbd8-b3daff836b80","html_url":"https://github.com/aleksandryackovlev/openapi-mock-express-middleware","commit_stats":{"total_commits":179,"total_committers":8,"mean_commits":22.375,"dds":"0.15083798882681565","last_synced_commit":"336d5281c69335de07fe61acb74df74f241fe4e4"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aleksandryackovlev%2Fopenapi-mock-express-middleware","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aleksandryackovlev%2Fopenapi-mock-express-middleware/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aleksandryackovlev%2Fopenapi-mock-express-middleware/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aleksandryackovlev%2Fopenapi-mock-express-middleware/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aleksandryackovlev","download_url":"https://codeload.github.com/aleksandryackovlev/openapi-mock-express-middleware/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248698956,"owners_count":21147564,"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":["codegen","express","middleware","mock","mock-server","openapi","swagger","typescript"],"created_at":"2025-03-10T12:25:51.082Z","updated_at":"2025-04-13T10:34:22.660Z","avatar_url":"https://github.com/aleksandryackovlev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://swagger.io/docs/specification/about/\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/aleksandryackovlev/openapi-mock-express-middleware/master/assets/openapi-logo.png\" alt=\"Open API logo\" width=\"200\" height=\"200\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/expressjs/express\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/aleksandryackovlev/openapi-mock-express-middleware/master/assets/express-logo.png\" alt=\"Express logo\" width=\"465\" height=\"141\"\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n[![npm][npm]][npm-url]\n[![Build Status](https://github.com/aleksandryackovlev/openapi-mock-express-middleware/workflows/build/badge.svg)](https://github.com/aleksandryackovlev/openapi-mock-express-middleware/actions)\n[![codecov](https://codecov.io/gh/aleksandryackovlev/openapi-mock-express-middleware/branch/master/graph/badge.svg)](https://codecov.io/gh/aleksandryackovlev/openapi-mock-express-middleware)\n[![size](https://packagephobia.now.sh/badge?p=openapi-mock-express-middleware)](https://packagephobia.now.sh/result?p=openapi-mock-express-middleware)\n\n# openapi-mock-express-middleware\n\nGenerates express mock-servers from [Open API 3.0](https://swagger.io/docs/specification/about/) specs.\n\n## Installation\n\nTo begin, you'll need to install `openapi-mock-express-middleware`:\n\n```console\n$ npm install openapi-mock-express-middleware --save-dev\n```\n\n## Usage\n### Simple Config\n```javascript\nconst express = require('express');\nconst { createMockMiddleware } = require('openapi-mock-express-middleware');\n\nconst app = express();\n\napp.use(\n  '/api', // root path for the mock server\n  createMockMiddleware({ spec: '/absolute/path/to/your/openapi/spec.yml' }),\n);\n\napp.listen(80, () =\u003e console.log('Server listening on port 80'));\n```\n\n### Advanced Config\nThe middleware uses [json-schmea-faker](https://github.com/json-schema-faker/json-schema-faker) under the hood. To configure it, you can pass the options object to the factory function. (The full list of available options can be seen [here](https://github.com/json-schema-faker/json-schema-faker/tree/master/docs#available-options))\n\n```javascript\nconst express = require('express');\nconst { createMockMiddleware } = require('openapi-mock-express-middleware');\n\nconst app = express();\n\napp.use(\n  '/api',\n  createMockMiddleware({\n    spec: '/absolute/path/to/your/openapi/spec.yml', // string or OpenAPIV3.Document object\n    options: { // json-schema-faker options\n      alwaysFakeOptionals: true,\n      useExamplesValue: true,\n      randomizeExamples: true, // choose a random example from the examples object; when set to false (default) the first example is used\n      // ...\n    },\n    configure: (jsf) =\u003e {\n    \t// function where you can extend json-schema-faker\n    \t...\n    }\n  }),\n);\n\napp.listen(80, () =\u003e console.log('Server listening on port 80'));\n```\n\n## Mock data\n### Basic behavior\nBy default midleware generates random responses depending on the types specified in the openapi docs.\n\n**doc.yml**\n```\n...\npaths:\n  /company\n    get:\n      responses:\n        '200':\n          content:\n            application/json:\n              schema:\n                type: object\n                required:\n                  - id\n                  - number\n                properties:\n                  id:\n                    type: string\n                  number:\n                type: integer\n...\n```\n\n**GET /company response**\n```javascript\n{\n  id: 'dolor veniam consequat laborum',\n  number: 68385409.\n}\n```\n\n### Faker or Chance generated responses\nIn addition `faker.js` or `chance.js` methods can be specified for data generation. In order to use these generators you have to configure middleware through the `configure` option of the factory function.\n\n```javascript\nconst express = require('express');\nconst { createMockMiddleware } = require('openapi-mock-express-middleware');\nimport faker from '@faker-js/faker';\nimport Chance from 'chance';\n\nconst app = express();\n\napp.use(\n  '/api',\n  createMockMiddleware({\n    spec: '/absolute/path/to/your/openapi/spec.yml',\n    configure: (jsf) =\u003e {\n    \tjsf.extend('faker', () =\u003e faker);\n\tjsf.extend('chance', () =\u003e new Chance());\n    }\n  }),\n);\n\napp.listen(80, () =\u003e console.log('Server listening on port 80'));\n\n```\n\nAfter that you can use 'x-faker' and/or 'x-chance' attributes in your openapi specs.\n\n**spec.yml**\n```\n...\npaths:\n  /user\n    get:\n      responses:\n        '200':\n          content:\n            application/json:\n              schema:\n                type: object\n                required:\n                  - id\n                  - name\n                properties:\n                  id:\n                    type: string\n                    x-faker: random.uuid\n                  name:\n                    type: string\n                    x-faker: name.findName\n                  email:\n                    type: string\n                    x-chance:\n                      email:\n                        domain: fake.com\t  \n...\n```\n\n**GET /user response**\n```javascript\n{\n  id: '8c4a4ed2-efba-4913-9604-19a27f36f322',\n  name: 'Mr. Braxton Dickens',\n  email: 'giigjom@fake.com'\n}\n```\n\n### Responses generated from examples\nIf an example for the response object is specified, it will be used as a resulting sever response.\n\n**doc.yml**\n```\n...\npaths:\n  /user\n    get:\n      responses:\n        '200':\n          content:\n            application/json:\n              schema:\n                type: object\n                example:\n                  id: 'id-125'\n                  name: 'John Smith'\n                required:\n                  - id\n                  - name\n                properties:\n                  id:\n                    type: string\n                    x-faker: random.uuid\n                  name:\n                    type: string\n                    x-faker: name.findName\n...\n```\n\n**GET /user response**\n```javascript\n{\n  id: 'id-125',\n  name: 'John Smith'.\n}\n```\n\nIf multiple examples for the response object are specified, the first one will be used as a resulting sever response.\n\n**doc.yml**\n```\n...\npaths:\n  /user\n    get:\n      responses:\n        '200':\n          content:\n            application/json:\n              schema:\n                type: object\n                examples:\n                  first:\n                    value:\n                      id: 'id-125'\n                      name: 'John Smith'\n                  second:\n                    value:\n                      id: 'some-other-id'\n                      name: 'Joe Doe'\n                required:\n                  - id\n                  - name\n                properties:\n                  id:\n                    type: string\n                    x-faker: random.uuid\n                  name:\n                    type: string\n                    x-faker: name.findName\n...\n```\n\n**GET /user response**\n```javascript\n{\n  id: 'id-125',\n  name: 'John Smith'.\n}\n```\n\nIf you want to use some other logic for generating responses from the `examples` attributes you can easily implement it by overwriting this behavior in the `configure` option of the middleware's factory function:\n\n```javascript\nconst express = require('express');\nconst { createMockMiddleware } = require('openapi-mock-express-middleware');\n\nconst app = express();\n\napp.use(\n  '/api',\n  createMockMiddleware({\n    spec: '/absolute/path/to/your/openapi/spec.yml',\n    configure: (jsf) =\u003e {\n      jsf.define('examples', (value) =\u003e {\n        if (typeof value === 'object' \u0026\u0026 value !== null \u0026\u0026 Object.keys(value).length) {\n          return value[Object.keys(value)[0]].value;\n        }\n\n        return '';\n      });\n    }\n  }),\n);\n\napp.listen(80, () =\u003e console.log('Server listening on port 80'));\n\n```\n\n## Contributing\n\nPlease take a moment to read our contributing guidelines if you haven't yet done so.\n\n[CONTRIBUTING](./.github/CONTRIBUTING.md)\n\n## License\n\n[MIT](./LICENSE)\n\n\n[npm]: https://img.shields.io/npm/v/openapi-mock-express-middleware.svg\n[npm-url]: https://npmjs.com/package/openapi-mock-express-middleware\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faleksandryackovlev%2Fopenapi-mock-express-middleware","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faleksandryackovlev%2Fopenapi-mock-express-middleware","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faleksandryackovlev%2Fopenapi-mock-express-middleware/lists"}