{"id":22772341,"url":"https://github.com/pactflow/swagger-mock-validator","last_synced_at":"2025-05-09T00:06:04.574Z","repository":{"id":37181729,"uuid":"483697756","full_name":"pactflow/swagger-mock-validator","owner":"pactflow","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-08T04:29:38.000Z","size":3516,"stargazers_count":16,"open_issues_count":13,"forks_count":7,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-05-09T00:05:50.578Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pactflow.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","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":"2022-04-20T14:53:20.000Z","updated_at":"2025-05-08T04:29:42.000Z","dependencies_parsed_at":"2024-06-19T15:00:02.565Z","dependency_job_id":"9872c55a-15e8-44ef-b558-3b876c5be549","html_url":"https://github.com/pactflow/swagger-mock-validator","commit_stats":{"total_commits":311,"total_committers":16,"mean_commits":19.4375,"dds":0.4951768488745981,"last_synced_commit":"b944ac7c4e69bcd09aa2a350d63708c064797dbc"},"previous_names":[],"tags_count":85,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pactflow%2Fswagger-mock-validator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pactflow%2Fswagger-mock-validator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pactflow%2Fswagger-mock-validator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pactflow%2Fswagger-mock-validator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pactflow","download_url":"https://codeload.github.com/pactflow/swagger-mock-validator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253166518,"owners_count":21864476,"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":[],"created_at":"2024-12-11T17:08:11.375Z","updated_at":"2025-05-09T00:06:04.562Z","avatar_url":"https://github.com/pactflow.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# UPDATE: new package\n\n\u003e [!IMPORTANT]  \n\u003e This package has been replaced by https://github.com/pactflow/openapi-pact-comparator/, which is a ground-up rewrite of this project. It's much faster (50x in many cases)\n\u003e and has numerous additional features and capabilities. This project is no longer incorporated into PactFlow's [Bi-Directional-Contract-Testing](https://pactflow.io/bi-directional-contract-testing) feature.\n\n# Swagger Mock Validator\n\u003e A CLI tool to validate mocks against swagger/OpenApi specs.\n\n## What is Swagger Mock Validator\n- A command line tool that confirms mock request and responses conform to the schema specified in a Swagger 2 or OpenApi 3 specification.\n- Supports mocks in Pact format (1.0, 1.1, 2.0, 3.0 and 4.0) and the [Pact Broker](https://github.com/bethesque/pact_broker) (1.8.0 or higher)\n- Supports local files and urls\n- Supports Swagger/OpenApi files in json or yaml format\n- Can be invoked from the command line in any language\n\nFor a list of all the validation features see [FEATURES.md](docs/FEATURES.md).\n\n## Requirements\n- nodejs 14.x or higher (tested using 14.x, 16.x and 16.x)\n\nNote: Beginning from v12+, this package is ESM-only, so you may need to upgrade your tooling to support this.\n\n## Installation\n\nInstall the tool globally using npm\n```\nnpm install --global @pactflow/swagger-mock-validator\n```\n\nInstall the tool a single project\n```\nnpm install --save-dev @pactflow/swagger-mock-validator\n```\n\nDownload and run the tool directly, without a global install, see [Usage](#usage)\n```\nnpx @pactflow/swagger-mock-validator /path/to/swagger.json /path/to/pact.json\n```\n\n## Usage\nInvoke the tool with a path or url to a Swagger or OpenApi file and a path or url to a mock file. These files should be in json format.\n```\nswagger-mock-validator /path/to/swagger.json /path/to/pact.json\n\nswagger-mock-validator https://api.com/swagger.json https://pact-broker.com/pact.json\n\nswagger-mock-validator /path/to/swagger.json https://pact-broker.com/pact.json\n```\n\nInvoking this command will confirm the Swagger/OpenApi spec and mock are compatible with each other. [FEATURES.md](docs/FEATURES.md) contains the details of what is verified.\n\nIf the two files are compatible with each other an exit status of 0 is returned.\n\nIf the two files are not compatible with each other an exit status of 1 is returned, along with a message containing the reason why the two files are not compatible.\n\nThe depth of the objects in the output can be modified by using `--outputDepth` flag, default depth is 4.\n```\nswagger-mock-validator spec.json mock.json --outputDepth 5\n```\n\nFor more options on how to use the command run the command with the help flag.\n\n`swagger-mock-validator --help`\n\n```bash\nUsage: swagger-mock-validator [options] \u003cswagger\u003e \u003cmock\u003e\n\nConfirms the swagger spec and mock are compatible with each other.\n\nBasic Usage:\nThe \u003cswagger\u003e and \u003cmock\u003e arguments should paths to the json files or urls to the json files.\n\nSupported Mock Formats:\nPact\n\nPact Broker:\nFor providers using the pact broker the \u003cmock\u003e argument should be the url to the root of the\npact broker and the provider name should be passed using the --provider option. This will\nautomatically find the latest versions of the consumer pact file(s) uploaded to the broker for\nthe specified provider name. The \u003cswagger\u003e argument should be the path or url to the swagger\njson file. Optionally, pass a --tag option alongside a --provider option to filter the retrieved\npacts from the broker by Pact Broker version tags. Pass the --publish flag together with\n--providerApplicationVersion to publish the result to the pact broker.\n\nIf the pact broker has basic auth enabled, pass a --user option with username and password joined by a colon\n(i.e. THE_USERNAME:THE_PASSWORD) to access the pact broker resources.\n\nIf the pact broker has bearer token auth enabled, pass a --token option along with the token to access the pact broker resources.\n\nYou can also set the following environment variables\n\n- Basic Auth\n  - `PACT_BROKER_USERNAME`\n  - `PACT_BROKER_PASSWORD`\n- Bearer Auth\n  - `PACT_BROKER_TOKEN`\n\nNote: command line options will take precedence over environment variables.\n\nOptions:\n  -V, --version                                   output the version number\n  -p, --provider [string]                         The name of the provider in the pact broker\n  -t, --tag [string]                              The tag to filter pacts retrieved from the pact broker\n  -u, --user [USERNAME:PASSWORD]                  The basic auth username and password to access the pact broker (env - PACT_BROKER_USERNAME:PACT_BROKER_PASSWORD)\n  -u, --token [string]                            The bearer token to access the pact broker (env - PACT_BROKER_TOKEN)\n  -a, --analyticsUrl [string]                     The url to send analytics events to as a http post\n  -o, --outputDepth [integer]                     Specifies the number of times to recurse while formatting the output objects. This is useful in case of large complicated objects or schemas. (default: 4)\n  -A, --additionalPropertiesInResponse [boolean]  allow additional properties in response bodies, default false\n  -R, --requiredPropertiesInResponse [boolean]    allows required properties in response bodies, default false\n  --publish                                       Allows publication of verification result to pact broker, default false\n  --providerApplicationVersion [string]           Version of provider, used when publishing result to broker, required if --publish is set\n  --buildUrl [string]                             Url to build/pipeline, used when publishing result to broker\n  --providerBranch [string]                       Branch of provider, used when publishing result to broker\n  --providerTags [string]                         Tags of provider, used when publishing result to broker, comma separated\n  -h, --help                                      display help for command\n\n```\n\n\n## Examples\n\nWe will demonstate with a sample Pact file and [Swagger PetStore Example](https://petstore.swagger.io/v2/swagger.json).\n\nIncluded in this repository is a [sample Pact file](./docs/pact.json) and the [Swagger Petstore Example file](./docs/swagger.json).\n\nThe swagger file has been modified to include `additionalProperties: true` in the `Pet` schema. This will be ignored with the default settings. \n\nset `--additionalPropertiesInResponse true` to preserve the intended behaviour.\n\n```json\n{\n  \"consumer\": {\n    \"name\": \"MyConsumer\"\n  },\n  \"provider\": {\n    \"name\": \"pactWith\"\n  },\n  \"interactions\": [\n    {\n      \"description\": \"A get request to get a pet 1845563262948980200\",\n      \"providerState\": \"A pet 1845563262948980200 exists\",\n      \"request\": {\n        \"method\": \"GET\",\n        \"path\": \"/v2/pet/1845563262948980200\",\n        \"headers\": {\n          \"api_key\": \"[]\"\n        }\n      },\n      \"response\": {\n        \"status\": 200,\n        \"headers\": {\n        },\n        \"body\": {\n          \"someField\": \"some string\"\n        },\n        \"matchingRules\": {\n          \"$.body.someField\": {\n            \"match\": \"type\"\n          }\n        }\n      }\n    }\n  ],\n  \"metadata\": {\n    \"pactSpecification\": {\n      \"version\": \"2.0.0\"\n    }\n  }\n}\n```\n\nDefault behaviour, as per the following flags \n\n- `--additionalPropertiesInResponse` false\n- `--requiredPropertiesInResponse` false\n\n`npx @pactflow/swagger-mock-validator ./docs/swagger.json ./docs/pact.json`\n\n```bash\nMock file \"./docs/pact.json\" is not compatible with spec file \"https://petstore.swagger.io/v2/swagger.json\"\n1 error(s)\n        response.body.incompatible: 1\n0 warning(s)\n{\n  warnings: [],\n  errors: [\n    {\n      code: 'response.body.incompatible',\n      message: 'Response body is incompatible with the response body schema in the spec file: should NOT have additional properties - someField',\n      mockDetails: {\n        interactionDescription: 'A get request to get a pet 1845563262948980200',\n        interactionState: 'A pet 1845563262948980200 exists',\n        location: '[root].interactions[0].response.body',\n        mockFile: './docs/pact.json',\n        value: { someField: 'some string' }\n      },\n      source: 'spec-mock-validation',\n      specDetails: {\n        location: '[root].paths./pet/{petId}.get.responses.200.schema.additionalProperties',\n        pathMethod: 'get',\n        pathName: '/pet/{petId}',\n        specFile: 'https://petstore.swagger.io/v2/swagger.json',\n        value: undefined\n      },\n      type: 'error'\n    }\n  ]\n}\n\nError: Mock file \"./docs/pact.json\" is not compatible with spec file \"https://petstore.swagger.io/v2/swagger.json\"\n```\n\nWith \n\n- `--additionalPropertiesInResponse` true\n- `--requiredPropertiesInResponse` false\n\n`npx @pactflow/swagger-mock-validator --additionalPropertiesInResponse true --requiredPropertiesInResponse false docs/swagger.json ./docs/pact.json`\n\n```bash\n0 error(s)\n0 warning(s)\n```\n\nWith \n\n- `--additionalPropertiesInResponse` false\n- `--requiredPropertiesInResponse` true\n\n`npx @pactflow/swagger-mock-validator --additionalPropertiesInResponse false --requiredPropertiesInResponse true docs/swagger.json ./docs/pact.json`\n\n```bash\n\nMock file \"./docs/pact.json\" is not compatible with spec file \"docs/swagger.json\"\n3 error(s)\n        response.body.incompatible: 3\n0 warning(s)\n{\n  warnings: [],\n  errors: [\n    {\n      code: 'response.body.incompatible',\n      message: 'Response body is incompatible with the response body schema in the spec file: should NOT have additional properties - someField',\n      mockDetails: {\n        interactionDescription: 'A get request to get a pet 1845563262948980200',\n        interactionState: 'A pet 1845563262948980200 exists',\n        location: '[root].interactions[0].response.body',\n        mockFile: './docs/pact.json',\n        value: { someField: 'some string' }\n      },\n      source: 'spec-mock-validation',\n      specDetails: {\n        location: '[root].paths./pet/{petId}.get.responses.200.schema.additionalProperties',\n        pathMethod: 'get',\n        pathName: '/pet/{petId}',\n        specFile: 'docs/swagger.json',\n        value: undefined\n      },\n      type: 'error'\n    },\n    {\n      code: 'response.body.incompatible',\n      message: \"Response body is incompatible with the response body schema in the spec file: should have required property 'name'\",\n      mockDetails: {\n        interactionDescription: 'A get request to get a pet 1845563262948980200',\n        interactionState: 'A pet 1845563262948980200 exists',\n        location: '[root].interactions[0].response.body',\n        mockFile: './docs/pact.json',\n        value: { someField: 'some string' }\n      },\n      source: 'spec-mock-validation',\n      specDetails: {\n        location: '[root].paths./pet/{petId}.get.responses.200.schema.required',\n        pathMethod: 'get',\n        pathName: '/pet/{petId}',\n        specFile: 'docs/swagger.json',\n        value: [ 'name', 'photoUrls' ]\n      },\n      type: 'error'\n    },\n    {\n      code: 'response.body.incompatible',\n      message: \"Response body is incompatible with the response body schema in the spec file: should have required property 'photoUrls'\",\n      mockDetails: {\n        interactionDescription: 'A get request to get a pet 1845563262948980200',\n        interactionState: 'A pet 1845563262948980200 exists',\n        location: '[root].interactions[0].response.body',\n        mockFile: './docs/pact.json',\n        value: { someField: 'some string' }\n      },\n      source: 'spec-mock-validation',\n      specDetails: {\n        location: '[root].paths./pet/{petId}.get.responses.200.schema.required',\n        pathMethod: 'get',\n        pathName: '/pet/{petId}',\n        specFile: 'docs/swagger.json',\n        value: [ 'name', 'photoUrls' ]\n      },\n      type: 'error'\n    }\n  ]\n}\n\nError: Mock file \"./docs/pact.json\" is not compatible with spec file \"docs/swagger.json\"\n```\n\nWith \n\n- `--additionalPropertiesInResponse` true\n- `--requiredPropertiesInResponse` true\n\n`npx @pactflow/swagger-mock-validator --additionalPropertiesInResponse true --requiredPropertiesInResponse true docs/swagger.json ./docs/pact.json`\n\n```bash\nMock file \"./docs/pact.json\" is not compatible with spec file \"docs/swagger.json\"\n2 error(s)\n        response.body.incompatible: 2\n0 warning(s)\n{\n  warnings: [],\n  errors: [\n    {\n      code: 'response.body.incompatible',\n      message: \"Response body is incompatible with the response body schema in the spec file: should have required property 'name'\",\n      mockDetails: {\n        interactionDescription: 'A get request to get a pet 1845563262948980200',\n        interactionState: 'A pet 1845563262948980200 exists',\n        location: '[root].interactions[0].response.body',\n        mockFile: './docs/pact.json',\n        value: { someField: 'some string' }\n      },\n      source: 'spec-mock-validation',\n      specDetails: {\n        location: '[root].paths./pet/{petId}.get.responses.200.schema.required',\n        pathMethod: 'get',\n        pathName: '/pet/{petId}',\n        specFile: 'docs/swagger.json',\n        value: [ 'name', 'photoUrls' ]\n      },\n      type: 'error'\n    },\n    {\n      code: 'response.body.incompatible',\n      message: \"Response body is incompatible with the response body schema in the spec file: should have required property 'photoUrls'\",\n      mockDetails: {\n        interactionDescription: 'A get request to get a pet 1845563262948980200',\n        interactionState: 'A pet 1845563262948980200 exists',\n        location: '[root].interactions[0].response.body',\n        mockFile: './docs/pact.json',\n        value: { someField: 'some string' }\n      },\n      source: 'spec-mock-validation',\n      specDetails: {\n        location: '[root].paths./pet/{petId}.get.responses.200.schema.required',\n        pathMethod: 'get',\n        pathName: '/pet/{petId}',\n        specFile: 'docs/swagger.json',\n        value: [ 'name', 'photoUrls' ]\n      },\n      type: 'error'\n    }\n  ]\n}\n\nError: Mock file \"./docs/pact.json\" is not compatible with spec file \"docs/swagger.json\"\n```\n### Providers using the Pact Broker\n\nProvider services can easily verify all the consumer pact files uploaded to a Pact Broker using this tool. Invoke the tool with a url to the Pact Broker along with the name of the provider service and the tool will automatically discover and validate the latest versions of the consumer pact files for the provider service.\n```\nswagger-mock-validator /path/to/swagger.json https://pact-broker.com --provider my-provider-name\n```\n\nAdditionally, provide a Pact Broker version tag alongside the name of the provider service to filter the retrieved consumer pacts for the provider by the given tag.\n```\nswagger-mock-validator /path/to/swagger.json https://pact-broker.com --provider my-provider-name --tag production\n```\n\nIf the Pact Broker is behind basic auth, you can pass credentials with the `--user` option while invoking the tool.\n```\nswagger-mock-validator /path/to/swagger.json https://pact-broker.com --provider my-provider-name --user BASIC_AUTH_USER:BASIC_AUTH_PASSWORD\n```\n\nYou can also use environment variables\n```\nPACT_BROKER_USERNAME=BASIC_AUTH_USER PACT_BROKER_PASSWORD=BASIC_AUTH_PASSWORD swagger-mock-validator /path/to/swagger.json https://pact-broker.com --provider my-provider-name\n```\n\nIf the Pact Broker is behind bearer auth, you can pass credentials with the `--token` option while invoking the tool.\n\n```\nswagger-mock-validator /path/to/swagger.json https://pact-broker.com --provider my-provider-name --token bar\n```\n\nYou can also use environment variables\n```\nPACT_BROKER_TOKEN=bar swagger-mock-validator /path/to/swagger.json https://pact-broker.com --provider my-provider-name\n```\n\n### Analytics (Opt-In)\n\nThe tool can be configured to send analytics events to a server of your choosing. Use the `--analyticsUrl` flag to pass a url that the tool should post the event to. The tool will send this event via a http post request and will timeout after 5 seconds. See [analytics.ts](lib/swagger-mock-validator/analytics.ts) for the post body schema.\n\n```\nswagger-mock-validator /path/to/swagger.json /path/to/pact.json --analyticsUrl https://analytics-server.com/event\n```\n\nAny errors sending the analytic events are ignored and do not impact the validation results, a successful validation that had an error while trying to send the analytic event is still a successful validation.\n\nBy default analytics are disabled. To protect your privacy this is an opt-in feature.\n\n## Frequently Asked Questions\nSee [FAQ.md](FAQ.md)\n\n## Changelog\nSee [CHANGELOG.md](CHANGELOG.md)\n\n## Contributing\nSee [CONTRIBUTING.md](docs/CONTRIBUTING.md)\n\n## License\nSee [LICENSE.txt](LICENSE.txt)\n\n## Acknowledgements \n\nThis repository is a fork of Atlassians swagger-mock-validator which resides on BitBucket https://bitbucket.org/atlassian/swagger-mock-validator/src/master/\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpactflow%2Fswagger-mock-validator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpactflow%2Fswagger-mock-validator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpactflow%2Fswagger-mock-validator/lists"}