radin/python-doc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fastapi doc : change Query and added path Param

Browse Source
This commit is contained in:
RadinPirouz
2026-01-22 23:59:35 +03:30
parent 6cf2b3c3ef
commit a2aed1117f
2 changed files with 238 additions and 184 deletions
Download Patch File Download Diff File Expand all files Collapse all files

184
Docs/Services/FastAPI/10-Query-Auth.md
View File

@@ -1,184 +0,0 @@
# 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

238
Docs/Services/FastAPI/10-Query-Path--AdvancedParm.md Normal file
View File

@@ -0,0 +1,238 @@
# FastAPI – Advanced Path and Query Parameters
This document demonstrates advanced usage of **path parameters** and **query parameters** in FastAPI, including:
* Validation rules
* Aliases
* Descriptions for OpenAPI
* Deprecation flags
* Clear separation of responsibilities between path and query parameters
---
## Example Application
Create or update `main.py` with the following content:
```python
from fastapi import FastAPI, Query, Path, status
from fastapi.responses import JSONResponse
app = FastAPI()
users_db = [
{"id": "1", "name": "radin"}
]
@app.get("/user/{target_id}")
def get_user_by_path(
target_id: int = Path(
...,
alias="User ID",
description="Enter target unique ID",
deprecated=True,
)
):
for item in users_db:
if int(item["id"]) == target_id:
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_by_query(
target: int | None = Query(
default=None,
gt=0,
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,
)
```
---
## Path Parameter Example
### Endpoint
```http
GET /user/{target_id}
```
**Example Request:**
```
/user/1
```
### Characteristics
* Always required
* Defined as part of the route
* Used to identify a specific resource
* Missing value results in **404 Not Found**
* Supports validation, aliases, and documentation metadata
---
## Query Parameter Example
### Endpoint
```http
GET /user?User%20ID=1
```
### Characteristics
* Optional by default
* Used for filtering and searching
* Not part of the route path
* Supports validation and documentation metadata
* Uses default values when not provided
---
## Advanced Parameter Configuration
### `Path()` Example
```python
Path(
...,
alias="User ID",
description="Enter target unique ID",
deprecated=True
)
```
* `...` → parameter is required
* `alias` → custom name in documentation and URL
* `description` → shown in Swagger UI
* `deprecated` → marked as deprecated in OpenAPI
---
### `Query()` Example
```python
Query(
default=None,
gt=0,
alias="User ID",
description="Enter target unique ID"
)
```
* `gt=0` → value must be greater than zero
* Optional parameter with validation rules
* Appears in API documentation
---
## Path vs Query Parameters
### 1. Path Parameters
**What they are**
Values embedded directly in the URL path that identify a specific resource.
**When to use**
When the parameter is mandatory and uniquely identifies a resource.
**Example URL**
```
/users/42
```
**FastAPI Example**
```python
@app.get("/users/{user_id}")
def get_user(user_id: int):
return {"user_id": user_id}
```
**Key Points**
* Always required
* Part of the route definition
* Used for IDs and unique identifiers
* Missing value → 404 error
---
### 2. Query Parameters
**What they are**
Key-value pairs appended to the URL after `?`.
**When to use**
For optional filtering, searching, sorting, and pagination.
**Example URL**
```
/users?limit=10&active=true
```
**FastAPI Example**
```python
@app.get("/users")
def list_users(limit: int = 10, active: bool = True):
return {"limit": limit, "active": active}
```
**Key Points**
* Optional by default
* Not part of the route path
* Used to modify or filter results
* Defaults are used when missing
---
## Side-by-Side Comparison
| Feature | Path Parameter | Query Parameter |
| ------------- | ------------------- | --------------------------------- |
| Location | Inside URL path | After `?` |
| Required | Yes | No (by default) |
| Purpose | Identify a resource | Filter or modify results |
| Example | `/items/5` | `/items?limit=10` |
| Missing Value | 404 Not Found | Default value or validation error |
---
## Best Practices
* Use path parameters for resource identification
* Use query parameters for filtering and modifiers
* Avoid spaces in parameter aliases for production APIs
* Deprecate parameters instead of removing them
* Use validation (`gt`, `lt`, `regex`) for safer APIs
* Keep URL design consistent across services
* Prefer response models over manual JSON responses when possible