{"id":13465598,"url":"https://github.com/tharlesamaro/fastapi-doc-http-response","last_synced_at":"2026-05-02T13:33:05.482Z","repository":{"id":142269767,"uuid":"613092171","full_name":"tharlesamaro/fastapi-doc-http-response","owner":"tharlesamaro","description":"A Python package to facilitate the definition of default HTTP responses for FastAPI APIs. With this package, it is possible to easily create default responses for the most common HTTP status codes.","archived":false,"fork":false,"pushed_at":"2023-03-18T02:44:43.000Z","size":26,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-23T04:42:03.050Z","etag":null,"topics":["api","development","fastapi","http","http-status-code","python","response","web"],"latest_commit_sha":null,"homepage":"","language":"Python","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/tharlesamaro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-03-12T21:12:47.000Z","updated_at":"2023-03-24T23:00:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"9d9967ff-8a7f-4c7e-8412-80feea5417bc","html_url":"https://github.com/tharlesamaro/fastapi-doc-http-response","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tharlesamaro/fastapi-doc-http-response","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tharlesamaro%2Ffastapi-doc-http-response","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tharlesamaro%2Ffastapi-doc-http-response/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tharlesamaro%2Ffastapi-doc-http-response/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tharlesamaro%2Ffastapi-doc-http-response/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tharlesamaro","download_url":"https://codeload.github.com/tharlesamaro/fastapi-doc-http-response/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tharlesamaro%2Ffastapi-doc-http-response/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32536576,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T12:25:33.646Z","status":"ssl_error","status_checked_at":"2026-05-02T12:24:51.733Z","response_time":132,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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","development","fastapi","http","http-status-code","python","response","web"],"created_at":"2024-07-31T15:00:32.425Z","updated_at":"2026-05-02T13:33:05.472Z","avatar_url":"https://github.com/tharlesamaro.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\u003e Para ler este README em portugues do Brasil, clique [aqui](https://github.com/tharlesamaro/fastapi-doc-http-response/blob/main/README_br.md).\n\n# FastAPI Doc HTTP Response\n\n[![PyPI](https://img.shields.io/pypi/v/fastapi_doc_http_response?color=blue)](https://pypi.org/project/fastapi-doc-http-response)\n[![Python](https://img.shields.io/pypi/pyversions/fastapi_doc_http_response)](https://pypi.org/project/fastapi-doc-http-response)\n[![Codecov](https://codecov.io/gh/tharlesamaro/fastapi-doc-http-response/branch/main/graph/badge.svg?token=VAY93FNZCA)](https://codecov.io/gh/tharlesamaro/fastapi-doc-http-response)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://opensource.org/license/mit/)\n\n## Why this package?\n\nFastAPI automatically generates interactive API documentation (Swagger UI / ReDoc), but by default it only shows a few HTTP response codes per route — usually just `200` and `422`. In real-world APIs, routes can return many other status codes (`400`, `401`, `403`, `404`, `409`, `500`, etc.), and documenting all of them manually is repetitive and verbose:\n\n```python\n# Without this package — verbose and repetitive\n@app.get(\n    \"/items/{item_id}\",\n    responses={\n        401: {\"description\": \"Unauthorized\", \"content\": {\"application/json\": {\"example\": {\"detail\": \"Unauthorized\"}}}},\n        403: {\"description\": \"Forbidden\", \"content\": {\"application/json\": {\"example\": {\"detail\": \"Forbidden\"}}}},\n        404: {\"description\": \"Not Found\", \"content\": {\"application/json\": {\"example\": {\"detail\": \"Not Found\"}}}},\n    },\n)\nasync def get_item(item_id: int): ...\n```\n\n**FastAPI Doc HTTP Response** solves this by providing a single function call that generates standard response definitions for any HTTP status code. Your documentation becomes complete and your code stays clean:\n\n```python\n# With this package — clean and simple\n@app.get(\"/items/{item_id}\", responses=get_responses(401, 403, 404))\nasync def get_item(item_id: int): ...\n```\n\n## Installation\n\n```bash\npip install fastapi-doc-http-response\n```\n\nRequires Python 3.13+.\n\n## Quick Start\n\n```python\nfrom fastapi import FastAPI\nfrom fastapi_doc_http_response import get_responses\n\napp = FastAPI()\n\n\n@app.get(\"/items\", responses=get_responses(401, 403))\nasync def list_items():\n    return [{\"id\": 1, \"name\": \"Item One\"}]\n\n\n@app.post(\"/items\", status_code=201, responses=get_responses(400, 401, 403, 409))\nasync def create_item(name: str):\n    return {\"id\": 2, \"name\": name}\n\n\n@app.get(\"/items/{item_id}\", responses=get_responses(401, 403, 404))\nasync def get_item(item_id: int):\n    ...\n```\n\nAll the specified status codes will automatically appear in the Swagger UI and ReDoc documentation with their standard descriptions and example response bodies.\n\n## API Reference\n\n### `get_responses(*codes) -\u003e dict`\n\nReturns a dictionary of FastAPI-compatible response definitions for the given HTTP status codes.\n\n```python\nfrom http import HTTPStatus\nfrom fastapi_doc_http_response import get_responses\n\n# Using integers\nget_responses(400, 401, 404)\n\n# Using strings\nget_responses(\"400\", \"401\", \"404\")\n\n# Using HTTPStatus enum\nget_responses(HTTPStatus.BAD_REQUEST, HTTPStatus.UNAUTHORIZED, HTTPStatus.NOT_FOUND)\n\n# Mixing types\nget_responses(400, \"401\", HTTPStatus.NOT_FOUND)\n```\n\nReturns an empty dict `{}` if no valid codes are provided (safe to pass directly to FastAPI).\n\n### `HTTP_RESPONSES`\n\nThe complete dictionary of all response definitions, indexed by integer status code. Useful for inspection or building custom response sets:\n\n```python\nfrom fastapi_doc_http_response import HTTP_RESPONSES\n\n# Check what's available\nprint(HTTP_RESPONSES[404])\n# {'description': 'Not Found', 'content': {'application/json': {'example': {'detail': 'Not Found'}}}}\n```\n\n### `__version__`\n\nThe package version string.\n\n## Supported Status Codes\n\nAll **63 IANA-registered HTTP status codes** from Python's `http.HTTPStatus` are supported, including:\n\n| Range | Examples |\n|-------|----------|\n| 1xx Informational | 100, 101, 102, 103 |\n| 2xx Success | 200, 201, 202, 204, 206, 207, 208, 226 |\n| 3xx Redirection | 300, 301, 302, 303, 304, 307, 308 |\n| 4xx Client Error | 400, 401, 403, 404, 405, 408, 409, 410, 413, 415, 418, 422, 429, 451 |\n| 5xx Server Error | 500, 501, 502, 503, 504, 507, 511 |\n\nAs new codes are added to Python's `http.HTTPStatus` in future versions, they will be automatically available.\n\n## Docker Demo\n\nTry it out with Docker:\n\n```bash\ndocker compose up --build\n```\n\nThen visit [http://localhost:8000/docs](http://localhost:8000/docs) to see the interactive documentation with all response codes.\n\n## Migration from v0.x\n\nIf you're upgrading from v0.x, note these **breaking changes**:\n\n| Change | Before (v0.x) | After (v1.0) |\n|--------|---------------|--------------|\n| Dict keys | String (`\"400\"`) | Integer (`400`) |\n| Empty result | `None` | `{}` |\n| Non-standard codes | 306, 420, 444, 449, 450, 494 included | Removed (IANA standard codes only) |\n| Python version | 3.10+ | 3.13+ |\n\n## License\n\nThis package is licensed under the [MIT License](https://opensource.org/license/mit/). See the [LICENSE](https://github.com/tharlesamaro/fastapi-doc-http-response/blob/main/LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftharlesamaro%2Ffastapi-doc-http-response","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftharlesamaro%2Ffastapi-doc-http-response","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftharlesamaro%2Ffastapi-doc-http-response/lists"}