185 lines
3.5 KiB
Markdown
185 lines
3.5 KiB
Markdown
# FastAPI – Advanced Query Parameters (`Query`)
|
||
|
||
This document demonstrates how to configure **query parameters** in FastAPI using `Query()` to add:
|
||
|
||
* Aliases
|
||
* Descriptions (for API documentation)
|
||
* Deprecation warnings
|
||
* Validation and metadata
|
||
|
||
It also shows how these configurations appear in the **OpenAPI / Swagger UI**.
|
||
|
||
---
|
||
|
||
## Example Application
|
||
|
||
Create or update `main.py` with the following content:
|
||
|
||
```python
|
||
from fastapi import FastAPI, Query, status
|
||
from fastapi.responses import JSONResponse
|
||
|
||
app = FastAPI()
|
||
|
||
users_db = [
|
||
{"id": "1", "name": "radin"}
|
||
]
|
||
|
||
|
||
@app.get("/user/")
|
||
def get_user_deprecated(
|
||
target: int | None = Query(
|
||
default=None,
|
||
alias="User ID",
|
||
description="Enter target unique ID",
|
||
deprecated=True,
|
||
)
|
||
):
|
||
for item in users_db:
|
||
if int(item["id"]) == target:
|
||
return JSONResponse(
|
||
content={"msg": f"Your target user name is {item['name']}"},
|
||
status_code=status.HTTP_200_OK,
|
||
)
|
||
|
||
return JSONResponse(
|
||
content={"msg": "user not found"},
|
||
status_code=status.HTTP_404_NOT_FOUND,
|
||
)
|
||
|
||
|
||
@app.get("/user")
|
||
def get_user(
|
||
target: int | None = Query(
|
||
default=None,
|
||
alias="User ID",
|
||
description="Enter target unique ID",
|
||
)
|
||
):
|
||
for item in users_db:
|
||
if item["id"] == str(target):
|
||
return JSONResponse(
|
||
content={"msg": f"Your target user name is {item['name']}"},
|
||
status_code=status.HTTP_200_OK,
|
||
)
|
||
|
||
return JSONResponse(
|
||
content={"msg": "user not found"},
|
||
status_code=status.HTTP_404_NOT_FOUND,
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## Query Parameter Configuration
|
||
|
||
### `Query()` Parameters Used
|
||
|
||
```python
|
||
Query(
|
||
default=None,
|
||
alias="User ID",
|
||
description="Enter target unique ID",
|
||
deprecated=True
|
||
)
|
||
```
|
||
|
||
| Parameter | Purpose |
|
||
| ------------- | ------------------------------------------- |
|
||
| `default` | Makes the query parameter optional |
|
||
| `alias` | Changes the query parameter name in the URL |
|
||
| `description` | Appears in Swagger UI documentation |
|
||
| `deprecated` | Marks the parameter as deprecated |
|
||
|
||
---
|
||
|
||
## Example Requests
|
||
|
||
### Using Alias in Query String
|
||
|
||
```http
|
||
GET /user?User%20ID=1
|
||
```
|
||
|
||
---
|
||
|
||
## Endpoint Behavior
|
||
|
||
### Deprecated Endpoint
|
||
|
||
```http
|
||
GET /user/
|
||
```
|
||
|
||
* Query parameter is marked as **deprecated**
|
||
* Swagger UI displays a warning
|
||
* Useful for backward compatibility
|
||
|
||
---
|
||
|
||
### Active Endpoint
|
||
|
||
```http
|
||
GET /user
|
||
```
|
||
|
||
* Uses the same alias and description
|
||
* Recommended for active usage
|
||
|
||
---
|
||
|
||
## Response Examples
|
||
|
||
### Success Response
|
||
|
||
```json
|
||
{
|
||
"msg": "Your target user name is radin"
|
||
}
|
||
```
|
||
|
||
Status Code: **200 OK**
|
||
|
||
---
|
||
|
||
### Failure Response
|
||
|
||
```json
|
||
{
|
||
"msg": "user not found"
|
||
}
|
||
```
|
||
|
||
Status Code: **404 Not Found**
|
||
|
||
---
|
||
|
||
## Swagger / OpenAPI Integration
|
||
|
||
* Alias appears as the query parameter name
|
||
* Description is visible in API docs
|
||
* Deprecated parameters are clearly marked
|
||
* Improves API discoverability and usability
|
||
|
||
---
|
||
|
||
## Running the Application
|
||
|
||
Start the service using `uvicorn`:
|
||
|
||
```bash
|
||
uvicorn main:app --reload
|
||
```
|
||
|
||
---
|
||
|
||
## Best Practices
|
||
|
||
* Use `Query()` for validation and documentation
|
||
* Avoid spaces in aliases for production APIs
|
||
* Deprecate parameters instead of removing them
|
||
* Keep backward compatibility during API evolution
|
||
* Prefer consistent parameter naming
|
||
* Use response models instead of manual `JSONResponse` when possible
|
||
|