{"id":21301703,"url":"https://github.com/funbox/plumbapius","last_synced_at":"2025-07-11T20:31:15.935Z","repository":{"id":50871299,"uuid":"279312839","full_name":"funbox/plumbapius","owner":"funbox","description":"Plugs and tools for validating HTTP requests and responses according to API Blueprint specs","archived":false,"fork":false,"pushed_at":"2021-10-15T12:48:53.000Z","size":261,"stargazers_count":14,"open_issues_count":0,"forks_count":2,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-07-05T17:35:33.512Z","etag":null,"topics":["api-blueprint","elixir","elixir-library","validation"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/funbox.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":"2020-07-13T13:38:28.000Z","updated_at":"2023-12-25T13:52:43.000Z","dependencies_parsed_at":"2022-09-26T21:41:19.799Z","dependency_job_id":null,"html_url":"https://github.com/funbox/plumbapius","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/funbox/plumbapius","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Fplumbapius","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Fplumbapius/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Fplumbapius/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Fplumbapius/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/funbox","download_url":"https://codeload.github.com/funbox/plumbapius/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Fplumbapius/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264892149,"owners_count":23679239,"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-blueprint","elixir","elixir-library","validation"],"created_at":"2024-11-21T15:50:23.587Z","updated_at":"2025-07-11T20:31:10.924Z","avatar_url":"https://github.com/funbox.png","language":"Elixir","readme":"# Plumbapius\n\n\u003cimg align=\"right\" width=\"160\" height=\"160\"\n     alt=\"Plumbapius avatar: a pipe with sparkles around\"\n     src=\"./logo.png\"\u003e\n\nTool for validation of HTTP requests \u0026 responses according to API Blueprint specs.\n\nIt can be used both in test and production environments.\n\n## Installation\n\n```elixir\ndef deps do\n  [\n    {:plumbapius, \"~\u003e 0.18.0\"}\n  ]\nend\n```\n\n## Preparing JSON schema\n\nPlumbapius requires conversion of APIB to JSON schema.\n\nSome mix tasks to make this process easier are included and described below.\nThese tasks are supposed to be run manually and resulting JSON schema has to be committed.\n\n### `plumbapius.get_docs`\n\n```bash\nmix plumbapius.get_docs -c ssh://git@some-repo.com/some-repo.git -b master\n```\n\nClones or updates repository with APIB to local folder (it is useful when APIB specs are stored in separate repo).\n\n### `plumbapius.setup_docs`\n\n```bash\nmix plumbapius.setup_docs --from ./.apib/api.apib --into doc.json\n```\n\nConverts APIB to JSON schema.\n\nIt requires following tools to be installed (globally or locally in Gemfile):\n\n- [drafter](https://github.com/apiaryio/drafter);\n- [tomograph](https://github.com/funbox/tomograph).\n\n## Usage\n\nPlumbapius implements [Plug behaviour](https://hexdocs.pm/plug/Plug.html).\n\nPlugs provided:\n\n- `Plumbapius.Plug.LogValidationError` — logs errors.\n- `Plumbapius.Plug.SendToSentryValidationError` — posts errors to Sentry.\n- `Plumbapius.Plug.RaiseValidationError` — raises error (useful for test environment).\n\n## Examples\n\nrouter.exs:\n\n```elixir\ndefmodule DogeApp.Api.Router do\n  use DogeApp.Api, :router\n\n  @json_schema_path \"../../doc.json\"\n\n  @external_resource @json_schema_path\n  @json_schema File.read!(@json_schema_path)\n\n  pipeline :api do\n    plug(:accepts, [\"json\"])\n    plug(Application.get_env(:doge_app, :plumbapius_plug), json_schema: @json_schema)\n  end\n\n # ...\n\nend\n```\n\ntest.exs:\n\n```elixir\nconfig :doge_app, plumbapius_plug: Plumbapius.Plug.RaiseValidationError\n```\n\nprod.exs:\n\n```elixir\nconfig :doge_app, plumbapius_plug: Plumbapius.Plug.SendToSentryValidationError\n```\n\n## Usage in tests\n\nIn case you need to ignore Plumbapius validations (for error handling testing etc.), you can use `Plumbapius.ignore`:\n\n```elixir\ntest \"replies with error if request contains malformed json\", %{conn: conn} do\n  response =\n    conn\n    |\u003e Plumbapius.ignore()\n    |\u003e post(\"\", @bad_params)\n    |\u003e json_response(400)\nend\n```\n\n## Checking coverage\n\nA simple mix task is provided to check uncovered requests.\n\nFirst configure `preferred_cli_env` for Plumbapius task:\n\n```elixir\ndef project do\n  [\n    preferred_cli_env: [\n      \"plumbapius.cover\": :test,\n    ]\n  ]\nend\n```\n\n```\n\u003e mix plumbapius.cover -s doc.json\n\nCovered cases:\n\n✔ POST  /bot/v1/{chatbot}/messages 202\n\nMissed cases:\n\n✖ POST  /bot/v1/{chatbot}/messages 400\n\nCoverage: 50.0%\n```\n\nTask fails with error code if coverage is below given min value:\n\n```\n\u003e mix plumbapius.cover -s doc.json --min-coverage=0.6\n\nCovered cases:\n\n✔ POST  /bot/v1/{chatbot}/messages 202\n\nMissed cases:\n\n✖ POST  /bot/v1/{chatbot}/messages 400\n\nCoverage: 50.0%\n\nERROR! min coverage of 50.0% is required\n```\n\nTo see request/response schemas use `-v` option:\n\n```\n\u003e mix plumbapius.cover -s doc.json -v\n```\n\nFor coverage that includes oneOfs and structs use `-m` option:\n\n```\n\u003e mix plumbapius.cover -s doc.json -m\n```\n\nYou can configure Plumbapius to ignore coverage for some requests:\n\n```elixir\nconfig :plumbapius, ignore_coverage: [\n  # {method :: String.t() | atom, path :: String.t() | Regex.t(), status :: pos_integer() | :all}\n  {\"GET\", \"/bot/v1/{chatbot}/messages\", 400},\n  {:all, \"/admin/users/\", :all},\n]\n```\n\n## Credits\n\nCute picture for the project was made by [Igor Garybaldi](http://pandabanda.com/).\n\n[![Sponsored by FunBox](https://funbox.ru/badges/sponsored_by_funbox_centered.svg)](https://funbox.ru)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffunbox%2Fplumbapius","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffunbox%2Fplumbapius","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffunbox%2Fplumbapius/lists"}