{"id":14986631,"url":"https://github.com/cachecontrol/hippie-swagger","last_synced_at":"2025-04-05T22:07:19.573Z","repository":{"id":36185381,"uuid":"40489554","full_name":"CacheControl/hippie-swagger","owner":"CacheControl","description":"API testing tool with automatic swagger assertions","archived":false,"fork":false,"pushed_at":"2022-12-10T16:16:09.000Z","size":543,"stargazers_count":180,"open_issues_count":10,"forks_count":24,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-05T22:07:06.111Z","etag":null,"topics":["api-testing","documentation","documentation-tool","hippie","swagger","swagger-spec"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CacheControl.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-08-10T15:16:24.000Z","updated_at":"2024-11-13T00:18:44.000Z","dependencies_parsed_at":"2023-01-16T23:46:03.635Z","dependency_job_id":null,"html_url":"https://github.com/CacheControl/hippie-swagger","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CacheControl%2Fhippie-swagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CacheControl%2Fhippie-swagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CacheControl%2Fhippie-swagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CacheControl%2Fhippie-swagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CacheControl","download_url":"https://codeload.github.com/CacheControl/hippie-swagger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247406089,"owners_count":20933803,"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-testing","documentation","documentation-tool","hippie","swagger","swagger-spec"],"created_at":"2024-09-24T14:13:15.321Z","updated_at":"2025-04-05T22:07:19.555Z","avatar_url":"https://github.com/CacheControl.png","language":"JavaScript","readme":"![hippie-swagger](http://i.imgur.com/icjd94P.png)\n\n_\"The confident hippie\"_\n\n[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com/)\n[![Build Status](https://github.com/cachecontrol/hippie-swagger/workflows/Node.js%20CI/badge.svg?branch=master)](https://github.com/cachecontrol/hippie-swagger/workflows/Node.js%20CI/badge.svg?branch=master)\n[![npm version](https://badge.fury.io/js/hippie-swagger.svg)](https://badge.fury.io/js/hippie-swagger)\n\n## Synopsis\n\n```hippie-swagger``` is a tool for testing RESTful APIs.  In addition to validating api behavior, it will fail tests when swagger documentation is missing or inaccurate.\n\nAs the test suite runs, any request or response details *not* matching the swagger file will throw an appropriate exception, failing the spec.  This ensures the swagger definition accurately describes application behavior, keeping documentation in sync with reality.\n\n```hippie-swagger``` uses [hippie](https://github.com/vesln/hippie) under the hood, an excellent API testing tool.\n\n## Features\n\n* All [hippie](https://github.com/vesln/hippie) features included\n* All aspects of swagger file validated; parameters, request/response body, paths, etc.\n* Checks for extra parameters, paths, headers, etc not mentioned in the swagger file\n* Ensures swagger file accurately describes API behavior\n* Accurate, human readable assertion messages\n\n## Installation\n\n```\nnpm install hippie-swagger --save-dev\n```\n\n## Basic Usage\n\n```js\nvar hippie = require('hippie-swagger'),\n    swagger = require('./my-dereferenced-swagger-file'); // see example for how to dereference swagger\n\nhippie(app, swagger)\n.get('/users/{username}')\n.pathParams({\n  username: 'cachecontrol'\n})\n.expectStatus(200)\n.expectValue('user.first', 'John')\n.expectHeader('cache-control', 'no-cache')\n.end(function(err, res, body) {\n  if (err) throw err;\n});\n```\n\n## Usage\n* See [hippie](https://github.com/vesln/hippie) documentation for a description of the base api\n* When specifying a url(.get, .post, .patch, .url, etc), use the [swagger path](http://swagger.io/specification/#pathsObject)\n* Provide any path variables using [pathParams](#pathparams)\n\nThese aside, use hippie as you normally would; see the [example](example/index.js).\n\n## Methods\n\n### #constructor (Object app, Object swagger, Object [options])\n\nTest an HTTP app (like express) directly\n\n```js\nhippie(app, swagger, options)\n.get('/projects')\n.end(fn);\n```\n\n### #constructor (Object swagger, Object [options])\n\nTest a remote HTTP app using a fully qualified url\n\n```js\nhippie(swagger, options)\n.get('http://localhost:3000/projects')\n.end(fn);\n```\n\n### #pathParams(Object hash)\n\nReplaces variables contained in the swagger path.\n\n```js\nhippie(app, swagger)\n.get('/projects/{projectId}/tasks/{taskId}')\n.pathParams({\n  projectId: 123,\n  taskId: 99\n})\n.end(fn);\n```\n\n## Options\n\nTo customize behavior, an ```options``` hash may be passed to the constructor.  Typically, ```options``` only need to be specified in situations where the test covers responses to improper requests (e.g. validating the application returns a 422 when a required parameter is not provided).\n\n```js\nvar options = {\n  validateResponseSchema: true,\n  validateParameterSchema: true,\n  errorOnExtraParameters: true,\n  errorOnExtraHeaderParameters: false\n};\nhippie(app, swagger, options)\n```\n\n```validateResponseSchema``` - Validate the server's response against the swagger json-schema definition (default: ```true```)\n\n```validateParameterSchema``` - Validate the request parameters against the swagger json-schema definition (default: ```true```)\n\n```validateRequiredParameters``` - Validate that required parameters were provided  (default: ```true```)\n\n```errorOnExtraParameters``` - Throw an error if a parameter is missing from the swagger file  (default: ```true```)\n\n```errorOnExtraHeaderParameters``` - Throw an error if a request header is missing from the swagger file.  By default this is turned off, because it results in every request needing to specify the \"Content-Type\" and \"Accept\" headers, which quickly becomes verbose. (default: ```false```)\n\n\n## Example\nSee the [example](example/index.js) folder\n\n## Validations\n\nWhen hippie-swagger detects it is interacting with the app in ways not specified in the swagger file, it will throw an error and fail the test.  The idea is to use hippie's core features to write API tests as per usual, and hippie-swagger will only interject if the swagger contract is violated.\n\nBelow are list of some of the validations that hippie-swagger checks for:\n\n### Paths\n```js\nhippie(app, swagger)\n.get('/pathNotMentionedInSwagger')\n.end(fn);\n// path does not exist in swagger file; throws:\n//    Swagger spec does not define path: pathNotMentionedInSwagger\n```\n\n### Parameter format\n```js\nhippie(app, swagger)\n.get('/users/{userId}')\n.pathParams({\n  userId: 'string-value',\n})\n.end(fn);\n// userId provided as a string, but swagger specifies it as an integer; throws:\n//    Invalid format for parameter {userId}\n```\n\n### Required Parameters\n```js\nhippie(app, swagger)\n.get('/users/{username}')\n.end(fn);\n// \"username\" is marked 'required' in swagger file; throws:\n//    Missing required parameter in path: username\n```\n\n### Extraneous Parameters\n```js\nhippie(app, swagger)\n.get('/users')\n.qs({ page: 2, limit: 30 })\n.end(fn);\n// \"page\" missing from swagger file; throws:\n//    Error: query parameter not mentioned in swagger spec: \"page\", available params: limit\n```\n\n### Response format\n```js\nhippie(app, swagger)\n.get('/users')\n.end(fn);\n// body failed to validate against swagger file's \"response\" schema; throws:\n//    Response from /users failed validation: [failure description]\n```\n\n### Method validation\n```js\nhippie(app, swagger)\n.post('/users')\n.end(fn);\n// \"post\" method not mentioned in swagger file; throws:\n//    Swagger spec does not define method: \"post\" in path /users\n```\n\n### Post body format\n```js\nhippie(app, swagger)\n.post('/users')\n.send({\"bogus\":\"post-body\"})\n.end(fn);\n\n// post body fails to validate against swagger file's \"body\" parameter; throws:\n//    Invalid format for parameter {body}, received: {\"bogus\":\"post-body\"}\n```\n\n### Form Url-Encoded Parameters\n```js\nhippie(app, swagger)\n.form()\n.post('/users')\n.send({})\n.end(fn);\n\n// \"username\" is {required: true, in: formData} in swagger; throws:\n//    Missing required parameter in formData: username\n```\n\n### Multipart Forms\n```js\nhippie(app, swagger)\n.header('Content-Type','multipart/form-data')\n.send()\n.post('/users/upload')\n.end(fn);\n\n// \"fileUpload\" is {required: true, in: formData, type: file} in swagger; throws:\n//    Missing required parameter in formData: fileUpload\n```\n\n## Troubleshooting\n\nThe most common mistake is forgetting to dereference the swagger file:\n\n```js\n\"'Error: cant resolve reference ...'\n```\n\nDereferencing can be accomplished using [swagger-parser](https://github.com/BigstickCarpet/swagger-parser/blob/master/docs/swagger-parser.md#dereferenceapi-options-callback).  The [example](example/index.js) gives a demonstration.\n\n## Contributing\n\nTo run the `hippie-swagger` tests:\n\n```\nnpm test\n```\n\n## License\n[ISC](./LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcachecontrol%2Fhippie-swagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcachecontrol%2Fhippie-swagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcachecontrol%2Fhippie-swagger/lists"}