{"id":21424197,"url":"https://github.com/mustafar/parrot","last_synced_at":"2025-07-14T08:31:42.041Z","repository":{"id":29815949,"uuid":"122852467","full_name":"mustafar/parrot","owner":"mustafar","description":"mockable, containerized api from your swagger spec.","archived":false,"fork":false,"pushed_at":"2023-09-29T15:13:37.000Z","size":750,"stargazers_count":8,"open_issues_count":11,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-04-15T02:56:33.857Z","etag":null,"topics":["api","container","docker","fake","integration-testing","mock","test","testing"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/mustafar/parrot/","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/mustafar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-25T16:15:03.000Z","updated_at":"2022-05-28T18:14:14.000Z","dependencies_parsed_at":"2023-01-14T15:42:32.259Z","dependency_job_id":null,"html_url":"https://github.com/mustafar/parrot","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mustafar%2Fparrot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mustafar%2Fparrot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mustafar%2Fparrot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mustafar%2Fparrot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mustafar","download_url":"https://codeload.github.com/mustafar/parrot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225965354,"owners_count":17552517,"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","container","docker","fake","integration-testing","mock","test","testing"],"created_at":"2024-11-22T21:20:02.980Z","updated_at":"2024-11-22T21:20:03.662Z","avatar_url":"https://github.com/mustafar.png","language":"JavaScript","readme":"# Parrot\nMockable, containerized API generated from a Swagger spec.\n**Docker Repo**: https://hub.docker.com/r/mustafar/parrot/\n\n# Getting started quickly\nIf you don't need to publish out a mock docker image of your service and just want to generate a quick container that mocks a swagger file you have, you can issue this command\n\n```\ndocker run -p 3000:3000 -v $(pwd):/myswagger -it --rm -e PORT=3000 -e SWAGGER_SPEC=\"/myswagger/swagger.yml\" mustafar/parrot:latest\n```\nThis assumes that swagger.yml exists in your current directory.\n\n# Build and run a docker image for a specific swagger file\nIf you're a service author and want to publish out a mocked and versioned copy of your service for consumers to use in their tests, you can build a docker image off of the parrot docker image.\n\n### Setup Dockerfile\n```\nFROM mustafar/parrot:latest\n\n# set the port for the mock api\nENV PORT=3000\n\n# copy a swagger spec to /swagger.yml (inside container)\n# and also set the path of swagger.yml in the container\nCOPY /path/to/a/swagger/or/openapi3/spec /spec.yml\nENV API_SPEC=\"/spec.yml\n```\n\n### Build container image\nRun the following command (in the same dir as the Dockerfile) to build your image\n```\ndocker build -t my_api .\n```\n\nYou may now publish this image to a docker repository.\n\n### Run container\nRun this command to start your container\n```\ndocker run -p 3000:3000 my_api:latest\n```\n\nThe `-p` directive sets up port forwarding from your container to host.\n\n# Testing\nOnce your API is up and running, you may call various API endpoints and receive either default or mocked responses.\n\n### Default response example\nConsider the following swagger route\n```\n/batman/location:\n  get:\n    x-swagger-router-controller: batman-location-controller\n    responses:\n      500:\n        description: failed to find batman\n      201:\n        example: alfred's outhouse # example is at an unexpected level\n      200:\n        schema:\n          type: string\n          example: batcave # example at correct level\n          description: batman found\n```\nParrot will return the **first** response with an `example` property nested under a `schema` property. It will response with the value of the `example` property (in this case `batcave (200)`).\n\n### Mocked response example\nCall `PUT /mock` to mock another route\n```js\n// mock\nconst mock = {\n  method: 'GET',\n  path: '/batman/location',\n  qs: 'hello=world\u0026foo=bar', // optional query string\n  status: 201,\n  response: 'arkham',\n};\nawait fetch(\n  `${apiBase}/mock`,\n  {\n    method: 'PUT',\n    body: JSON.stringify(mock),\n    headers: { 'content-type': 'application/json' }\n  },\n);\n\n// invoke (should return \"arkham (201)\")\nawait fetch(`${apiBase}/batman/location?hello=world\u0026foo=bar`, { method: 'GET' });\n```\n\n`DELETE /mock` will reset all mocked behavor.\n\nTo enable verbose logging, set `VERBOSE` environment variable when running the container\n```\n-e VERBOSE=on\n```\n\nCheck out the [tests](https://github.com/mustafar/parrot/blob/master/__tests__/tests.js) for more examples!\n\n# Contributing\nSpin up the test container with this command\n```\nnpm run build \u0026\u0026 npm run test:setup\n```\n\nRun tests with\n```\nnpm test\n```\n\nPlease feel free to send me a PR or open an [Issue](https://github.com/mustafar/parrot/issues).\n\n# OpenApi 3 Support\n\nTo use an OpenApi 3 spec, please set any value for environment variable `IS_OAS3`.\n\nExample:\n```\ndocker run -d --name parrot-container-openapi3 \\\n-e PORT=15010 \\\n-e VERBOSE=on \\\n-p 15010:15010 \\\n-e API_SPEC=\"/spec.yml\" \\\n-e IS_OAS3=\"true\" \\\n-v openapi3_spec.yaml:/spec.yml \\\nmustafar/parrot:latest\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmustafar%2Fparrot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmustafar%2Fparrot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmustafar%2Fparrot/lists"}