https://github.com/tharlesamaro/fastapi-doc-http-response
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.
https://github.com/tharlesamaro/fastapi-doc-http-response
api development fastapi http http-status-code python response web
Last synced: about 1 month ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/tharlesamaro/fastapi-doc-http-response
- Owner: tharlesamaro
- License: mit
- Created: 2023-03-12T21:12:47.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-03-18T02:44:43.000Z (about 3 years ago)
- Last Synced: 2025-09-23T04:42:03.050Z (9 months ago)
- Topics: api, development, fastapi, http, http-status-code, python, response, web
- Language: Python
- Homepage:
- Size: 25.4 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
> Para ler este README em portugues do Brasil, clique [aqui](https://github.com/tharlesamaro/fastapi-doc-http-response/blob/main/README_br.md).
# FastAPI Doc HTTP Response
[](https://pypi.org/project/fastapi-doc-http-response)
[](https://pypi.org/project/fastapi-doc-http-response)
[](https://codecov.io/gh/tharlesamaro/fastapi-doc-http-response)
[](https://opensource.org/license/mit/)
## Why this package?
FastAPI 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:
```python
# Without this package — verbose and repetitive
@app.get(
"/items/{item_id}",
responses={
401: {"description": "Unauthorized", "content": {"application/json": {"example": {"detail": "Unauthorized"}}}},
403: {"description": "Forbidden", "content": {"application/json": {"example": {"detail": "Forbidden"}}}},
404: {"description": "Not Found", "content": {"application/json": {"example": {"detail": "Not Found"}}}},
},
)
async def get_item(item_id: int): ...
```
**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:
```python
# With this package — clean and simple
@app.get("/items/{item_id}", responses=get_responses(401, 403, 404))
async def get_item(item_id: int): ...
```
## Installation
```bash
pip install fastapi-doc-http-response
```
Requires Python 3.13+.
## Quick Start
```python
from fastapi import FastAPI
from fastapi_doc_http_response import get_responses
app = FastAPI()
@app.get("/items", responses=get_responses(401, 403))
async def list_items():
return [{"id": 1, "name": "Item One"}]
@app.post("/items", status_code=201, responses=get_responses(400, 401, 403, 409))
async def create_item(name: str):
return {"id": 2, "name": name}
@app.get("/items/{item_id}", responses=get_responses(401, 403, 404))
async def get_item(item_id: int):
...
```
All the specified status codes will automatically appear in the Swagger UI and ReDoc documentation with their standard descriptions and example response bodies.
## API Reference
### `get_responses(*codes) -> dict`
Returns a dictionary of FastAPI-compatible response definitions for the given HTTP status codes.
```python
from http import HTTPStatus
from fastapi_doc_http_response import get_responses
# Using integers
get_responses(400, 401, 404)
# Using strings
get_responses("400", "401", "404")
# Using HTTPStatus enum
get_responses(HTTPStatus.BAD_REQUEST, HTTPStatus.UNAUTHORIZED, HTTPStatus.NOT_FOUND)
# Mixing types
get_responses(400, "401", HTTPStatus.NOT_FOUND)
```
Returns an empty dict `{}` if no valid codes are provided (safe to pass directly to FastAPI).
### `HTTP_RESPONSES`
The complete dictionary of all response definitions, indexed by integer status code. Useful for inspection or building custom response sets:
```python
from fastapi_doc_http_response import HTTP_RESPONSES
# Check what's available
print(HTTP_RESPONSES[404])
# {'description': 'Not Found', 'content': {'application/json': {'example': {'detail': 'Not Found'}}}}
```
### `__version__`
The package version string.
## Supported Status Codes
All **63 IANA-registered HTTP status codes** from Python's `http.HTTPStatus` are supported, including:
| Range | Examples |
|-------|----------|
| 1xx Informational | 100, 101, 102, 103 |
| 2xx Success | 200, 201, 202, 204, 206, 207, 208, 226 |
| 3xx Redirection | 300, 301, 302, 303, 304, 307, 308 |
| 4xx Client Error | 400, 401, 403, 404, 405, 408, 409, 410, 413, 415, 418, 422, 429, 451 |
| 5xx Server Error | 500, 501, 502, 503, 504, 507, 511 |
As new codes are added to Python's `http.HTTPStatus` in future versions, they will be automatically available.
## Docker Demo
Try it out with Docker:
```bash
docker compose up --build
```
Then visit [http://localhost:8000/docs](http://localhost:8000/docs) to see the interactive documentation with all response codes.
## Migration from v0.x
If you're upgrading from v0.x, note these **breaking changes**:
| Change | Before (v0.x) | After (v1.0) |
|--------|---------------|--------------|
| Dict keys | String (`"400"`) | Integer (`400`) |
| Empty result | `None` | `{}` |
| Non-standard codes | 306, 420, 444, 449, 450, 494 included | Removed (IANA standard codes only) |
| Python version | 3.10+ | 3.13+ |
## License
This 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.