Browse Source

Add LLM-friendly API documentation

This commit adds a comprehensive LLM.md file containing:
- Complete API reference for FastAPI classes and methods
- Usage examples with proper code snippets
- Parameter descriptions and return types
- Structured documentation optimized for LLM consumption

The documentation covers all major FastAPI components including:
- Core FastAPI application class
- Request/Response handling
- Dependency injection system
- Security and authentication
- Background tasks and middleware
- WebSocket support
- Testing utilities
pull/13895/head
Askdev.AI 3 weeks ago
parent
commit
8c2e9a89ce
  1. 914
      LLM.md

914
LLM.md

@ -0,0 +1,914 @@
# FastAPI Library API Documentation
FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.7+ based on standard Python type hints.
## Installation
```bash
pip install fastapi
pip install "uvicorn[standard]" # ASGI server
```
## Core Application
### FastAPI Class
```python
from fastapi import FastAPI
class FastAPI(Starlette):
"""FastAPI app class, the main entrypoint to use FastAPI."""
```
### Constructor Parameters
```python
app = FastAPI(
debug: bool = False,
routes: Optional[List[BaseRoute]] = None,
title: str = "FastAPI",
summary: Optional[str] = None,
description: str = "",
version: str = "0.1.0",
openapi_url: Optional[str] = "/openapi.json",
openapi_tags: Optional[List[Dict[str, Any]]] = None,
servers: Optional[List[Dict[str, Union[str, Any]]]] = None,
dependencies: Optional[Sequence[Depends]] = None,
default_response_class: Type[Response] = JSONResponse,
redirect_slashes: bool = True,
docs_url: Optional[str] = "/docs",
redoc_url: Optional[str] = "/redoc",
swagger_ui_oauth2_redirect_url: Optional[str] = "/docs/oauth2-redirect",
swagger_ui_init_oauth: Optional[Dict[str, Any]] = None,
middleware: Optional[Sequence[Middleware]] = None,
exception_handlers: Optional[Dict[Union[int, Type[Exception]], Callable]] = None,
on_startup: Optional[Sequence[Callable]] = None,
on_shutdown: Optional[Sequence[Callable]] = None,
lifespan: Optional[Lifespan] = None,
terms_of_service: Optional[str] = None,
contact: Optional[Dict[str, Union[str, Any]]] = None,
license_info: Optional[Dict[str, Union[str, Any]]] = None,
openapi_prefix: str = "",
root_path: str = "",
root_path_in_servers: bool = True,
responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None,
callbacks: Optional[List[BaseRoute]] = None,
webhooks: Optional[APIRouter] = None,
deprecated: Optional[bool] = None,
include_in_schema: bool = True,
swagger_ui_parameters: Optional[Dict[str, Any]] = None,
generate_unique_id_function: Callable[[APIRoute], str] = generate_unique_id,
separate_input_output_schemas: bool = True,
)
```
### HTTP Method Decorators
```python
@app.get(path: str, **kwargs)
@app.post(path: str, **kwargs)
@app.put(path: str, **kwargs)
@app.delete(path: str, **kwargs)
@app.patch(path: str, **kwargs)
@app.options(path: str, **kwargs)
@app.head(path: str, **kwargs)
@app.trace(path: str, **kwargs)
```
### Core Methods
```python
app.api_route(path: str, methods: List[str], **kwargs)
app.add_api_route(path: str, endpoint: Callable, **kwargs)
app.websocket(path: str, **kwargs)
app.include_router(router: APIRouter, prefix: str = "", **kwargs)
app.openapi() -> Dict[str, Any]
```
## Routing and Path Operations
### APIRouter
```python
from fastapi import APIRouter
router = APIRouter(
prefix: str = "",
tags: Optional[List[Union[str, Enum]]] = None,
dependencies: Optional[Sequence[Depends]] = None,
default_response_class: Type[Response] = JSONResponse,
responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None,
callbacks: Optional[List[BaseRoute]] = None,
routes: Optional[List[routing.BaseRoute]] = None,
redirect_slashes: bool = True,
default: Optional[ASGIApp] = None,
dependency_overrides_provider: Optional[Any] = None,
route_class: Type[APIRoute] = APIRoute,
on_startup: Optional[Sequence[Callable[[], Any]]] = None,
on_shutdown: Optional[Sequence[Callable[[], Any]]] = None,
lifespan: Optional[Lifespan[Any]] = None,
deprecated: Optional[bool] = None,
include_in_schema: bool = True,
generate_unique_id_function: Callable[[APIRoute], str] = generate_unique_id,
)
```
### Router Methods
```python
# HTTP method decorators (same as FastAPI app)
@router.get(path: str, **kwargs)
@router.post(path: str, **kwargs)
@router.put(path: str, **kwargs)
@router.delete(path: str, **kwargs)
@router.patch(path: str, **kwargs)
@router.options(path: str, **kwargs)
@router.head(path: str, **kwargs)
@router.trace(path: str, **kwargs)
# Core methods
router.api_route(path: str, methods: List[str], **kwargs)
router.add_api_route(path: str, endpoint: Callable, **kwargs)
router.websocket(path: str, **kwargs)
router.include_router(router: APIRouter, **kwargs)
```
## Parameter Functions
### Path Parameters
```python
from fastapi import Path
def Path(
default: Any = ...,
*,
alias: Optional[str] = None,
title: Optional[str] = None,
description: Optional[str] = None,
gt: Optional[float] = None,
ge: Optional[float] = None,
lt: Optional[float] = None,
le: Optional[float] = None,
min_length: Optional[int] = None,
max_length: Optional[int] = None,
regex: Optional[str] = None,
example: Any = Undefined,
examples: Optional[Dict[str, Any]] = None,
deprecated: Optional[bool] = None,
include_in_schema: bool = True,
**extra: Any,
) -> Any
```
### Query Parameters
```python
from fastapi import Query
def Query(
default: Any = Undefined,
*,
alias: Optional[str] = None,
title: Optional[str] = None,
description: Optional[str] = None,
gt: Optional[float] = None,
ge: Optional[float] = None,
lt: Optional[float] = None,
le: Optional[float] = None,
min_length: Optional[int] = None,
max_length: Optional[int] = None,
regex: Optional[str] = None,
example: Any = Undefined,
examples: Optional[Dict[str, Any]] = None,
deprecated: Optional[bool] = None,
include_in_schema: bool = True,
**extra: Any,
) -> Any
```
### Request Body
```python
from fastapi import Body
def Body(
default: Any = Undefined,
*,
embed: bool = False,
media_type: str = "application/json",
alias: Optional[str] = None,
title: Optional[str] = None,
description: Optional[str] = None,
gt: Optional[float] = None,
ge: Optional[float] = None,
lt: Optional[float] = None,
le: Optional[float] = None,
min_length: Optional[int] = None,
max_length: Optional[int] = None,
regex: Optional[str] = None,
example: Any = Undefined,
examples: Optional[Dict[str, Any]] = None,
**extra: Any,
) -> Any
```
### Headers and Cookies
```python
from fastapi import Header, Cookie
def Header(
default: Any = Undefined,
*,
alias: Optional[str] = None,
convert_underscores: bool = True,
title: Optional[str] = None,
description: Optional[str] = None,
gt: Optional[float] = None,
ge: Optional[float] = None,
lt: Optional[float] = None,
le: Optional[float] = None,
min_length: Optional[int] = None,
max_length: Optional[int] = None,
regex: Optional[str] = None,
example: Any = Undefined,
examples: Optional[Dict[str, Any]] = None,
deprecated: Optional[bool] = None,
include_in_schema: bool = True,
**extra: Any,
) -> Any
def Cookie(
default: Any = Undefined,
*,
alias: Optional[str] = None,
title: Optional[str] = None,
description: Optional[str] = None,
gt: Optional[float] = None,
ge: Optional[float] = None,
lt: Optional[float] = None,
le: Optional[float] = None,
min_length: Optional[int] = None,
max_length: Optional[int] = None,
regex: Optional[str] = None,
example: Any = Undefined,
examples: Optional[Dict[str, Any]] = None,
deprecated: Optional[bool] = None,
include_in_schema: bool = True,
**extra: Any,
) -> Any
```
### Form Data and File Uploads
```python
from fastapi import Form, File, UploadFile
def Form(
default: Any = Undefined,
*,
media_type: str = "application/x-www-form-urlencoded",
alias: Optional[str] = None,
title: Optional[str] = None,
description: Optional[str] = None,
gt: Optional[float] = None,
ge: Optional[float] = None,
lt: Optional[float] = None,
le: Optional[float] = None,
min_length: Optional[int] = None,
max_length: Optional[int] = None,
regex: Optional[str] = None,
example: Any = Undefined,
examples: Optional[Dict[str, Any]] = None,
**extra: Any,
) -> Any
def File(
default: Any = Undefined,
*,
media_type: str = "multipart/form-data",
alias: Optional[str] = None,
title: Optional[str] = None,
description: Optional[str] = None,
gt: Optional[float] = None,
ge: Optional[float] = None,
lt: Optional[float] = None,
le: Optional[float] = None,
min_length: Optional[int] = None,
max_length: Optional[int] = None,
example: Any = Undefined,
examples: Optional[Dict[str, Any]] = None,
**extra: Any,
) -> Any
```
## Dependency Injection
### Depends Function
```python
from fastapi import Depends
def Depends(
dependency: Optional[Callable[..., Any]] = None,
*,
use_cache: bool = True,
) -> Any
```
### Security Function
```python
from fastapi import Security
def Security(
dependency: Optional[Callable[..., Any]] = None,
*,
scopes: Optional[Sequence[str]] = None,
use_cache: bool = True,
) -> Any
```
## Security and Authentication
### API Key Authentication
```python
from fastapi.security import APIKeyQuery, APIKeyHeader, APIKeyCookie
# API key in query parameters
api_key_query = APIKeyQuery(name="api_key", auto_error=True)
# API key in headers
api_key_header = APIKeyHeader(name="X-API-Key", auto_error=True)
# API key in cookies
api_key_cookie = APIKeyCookie(name="api_key", auto_error=True)
```
### HTTP Authentication
```python
from fastapi.security import HTTPBasic, HTTPBearer, HTTPDigest
from fastapi.security.http import HTTPBasicCredentials, HTTPAuthorizationCredentials
# HTTP Basic authentication
basic_auth = HTTPBasic(auto_error=True)
# HTTP Bearer token
bearer_auth = HTTPBearer(auto_error=True)
# HTTP Digest authentication
digest_auth = HTTPDigest(auto_error=True)
```
### OAuth2 Authentication
```python
from fastapi.security import OAuth2PasswordBearer, OAuth2AuthorizationCodeBearer
from fastapi.security.oauth2 import OAuth2PasswordRequestForm, SecurityScopes
# OAuth2 password bearer
oauth2_scheme = OAuth2PasswordBearer(
tokenUrl="token",
scopes={"read": "Read access", "write": "Write access"},
auto_error=True
)
# OAuth2 authorization code
oauth2_code = OAuth2AuthorizationCodeBearer(
authorizationUrl="https://example.com/auth",
tokenUrl="https://example.com/token",
auto_error=True
)
```
### OpenID Connect
```python
from fastapi.security.open_id_connect_url import OpenIdConnect
openid_connect = OpenIdConnect(
openIdConnectUrl="https://example.com/.well-known/openid_configuration",
auto_error=True
)
```
## Response Types
### Standard Responses
```python
from fastapi.responses import (
Response, JSONResponse, HTMLResponse, PlainTextResponse,
RedirectResponse, StreamingResponse, FileResponse
)
# JSON response (default)
return JSONResponse(content={"message": "Hello World"})
# HTML response
return HTMLResponse(content="<html><body><h1>Hello World</h1></body></html>")
# Plain text response
return PlainTextResponse(content="Hello World")
# Redirect response
return RedirectResponse(url="https://example.com")
# File response
return FileResponse(path="/path/to/file.pdf", filename="download.pdf")
# Streaming response
def generate():
for i in range(1000):
yield f"data chunk {i}\n"
return StreamingResponse(generate(), media_type="text/plain")
```
### High-Performance JSON Responses
```python
from fastapi.responses import UJSONResponse, ORJSONResponse
# Ultra-fast JSON with ujson
return UJSONResponse(content={"message": "Fast JSON"})
# Ultra-fast JSON with orjson
return ORJSONResponse(content={"message": "Faster JSON"})
```
## Exception Handling
### HTTP Exceptions
```python
from fastapi import HTTPException
from fastapi.exceptions import (
RequestValidationError, WebSocketRequestValidationError,
ResponseValidationError, FastAPIError
)
# Raise HTTP exception
raise HTTPException(
status_code=404,
detail="Item not found",
headers={"X-Error": "There goes my error"}
)
# Custom exception handler
from fastapi.exception_handlers import (
http_exception_handler,
request_validation_exception_handler,
validation_exception_handler
)
@app.exception_handler(HTTPException)
async def custom_http_exception_handler(request, exc):
return await http_exception_handler(request, exc)
```
### WebSocket Exceptions
```python
from fastapi import WebSocketException
# Raise WebSocket exception
raise WebSocketException(code=1008, reason="Invalid data")
```
## WebSocket Support
### WebSocket Endpoint
```python
from fastapi import WebSocket, WebSocketDisconnect
from fastapi.websockets import WebSocketState
@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
await websocket.accept()
try:
while True:
data = await websocket.receive_text()
await websocket.send_text(f"Message: {data}")
except WebSocketDisconnect:
print("Client disconnected")
```
### WebSocket Methods
```python
# Connection management
await websocket.accept(subprotocol=None)
await websocket.close(code=1000)
# Receiving data
data = await websocket.receive() # Any message
text = await websocket.receive_text() # Text message
bytes_data = await websocket.receive_bytes() # Binary message
json_data = await websocket.receive_json() # JSON message
# Sending data
await websocket.send(message)
await websocket.send_text(data)
await websocket.send_bytes(data)
await websocket.send_json(data)
# Iterating over messages
async for message in websocket.iter_text():
print(message)
async for message in websocket.iter_bytes():
print(message)
async for message in websocket.iter_json():
print(message)
```
### WebSocket States
```python
from fastapi.websockets import WebSocketState
# WebSocketState.CONNECTING
# WebSocketState.CONNECTED
# WebSocketState.DISCONNECTED
if websocket.client_state == WebSocketState.CONNECTED:
await websocket.send_text("Hello")
```
## Background Tasks
### Background Task Execution
```python
from fastapi import BackgroundTasks
def write_log(message: str):
with open("log.txt", mode="a") as log:
log.write(message)
@app.post("/send-notification/")
async def send_notification(email: str, background_tasks: BackgroundTasks):
background_tasks.add_task(write_log, f"Notification sent to {email}")
return {"message": "Notification sent in the background"}
```
## Testing
### TestClient
```python
from fastapi.testclient import TestClient
client = TestClient(app)
# HTTP requests
response = client.get("/")
response = client.post("/items/", json={"name": "Foo"})
response = client.put("/items/1", json={"name": "Bar"})
response = client.delete("/items/1")
# WebSocket testing
with client.websocket_connect("/ws") as websocket:
websocket.send_text("Hello")
data = websocket.receive_text()
assert data == "Message: Hello"
# File uploads
with open("test.txt", "rb") as f:
response = client.post("/upload/", files={"file": f})
# Form data
response = client.post("/form/", data={"username": "testuser"})
```
## Middleware
### CORS Middleware
```python
from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(
CORSMiddleware,
allow_origins=["https://example.com"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
```
### Other Middleware
```python
from fastapi.middleware.gzip import GZipMiddleware
from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware
from fastapi.middleware.trustedhost import TrustedHostMiddleware
# GZip compression
app.add_middleware(GZipMiddleware, minimum_size=1000)
# HTTPS redirect
app.add_middleware(HTTPSRedirectMiddleware)
# Trusted host validation
app.add_middleware(
TrustedHostMiddleware,
allowed_hosts=["example.com", "*.example.com"]
)
```
## Utilities
### JSON Encoder
```python
from fastapi.encoders import jsonable_encoder
from datetime import datetime
from pydantic import BaseModel
class Item(BaseModel):
name: str
timestamp: datetime
item = Item(name="Foo", timestamp=datetime.now())
json_data = jsonable_encoder(item)
```
### Static Files
```python
from fastapi.staticfiles import StaticFiles
app.mount("/static", StaticFiles(directory="static"), name="static")
```
## Status Codes
```python
from fastapi import status
@app.post("/items/", status_code=status.HTTP_201_CREATED)
def create_item():
return {"message": "Item created"}
# Common status codes
status.HTTP_200_OK
status.HTTP_201_CREATED
status.HTTP_204_NO_CONTENT
status.HTTP_400_BAD_REQUEST
status.HTTP_401_UNAUTHORIZED
status.HTTP_403_FORBIDDEN
status.HTTP_404_NOT_FOUND
status.HTTP_422_UNPROCESSABLE_ENTITY
status.HTTP_500_INTERNAL_SERVER_ERROR
```
## Complete Usage Examples
### Basic FastAPI Application
```python
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Optional
app = FastAPI(title="My API", version="1.0.0")
class Item(BaseModel):
name: str
description: Optional[str] = None
price: float
tax: Optional[float] = None
items_db = []
@app.get("/")
def read_root():
return {"Hello": "World"}
@app.get("/items/{item_id}")
def read_item(item_id: int, q: Optional[str] = None):
if item_id >= len(items_db):
raise HTTPException(status_code=404, detail="Item not found")
return {"item_id": item_id, "q": q, "item": items_db[item_id]}
@app.post("/items/")
def create_item(item: Item):
items_db.append(item)
return item
@app.put("/items/{item_id}")
def update_item(item_id: int, item: Item):
if item_id >= len(items_db):
raise HTTPException(status_code=404, detail="Item not found")
items_db[item_id] = item
return item
@app.delete("/items/{item_id}")
def delete_item(item_id: int):
if item_id >= len(items_db):
raise HTTPException(status_code=404, detail="Item not found")
return items_db.pop(item_id)
```
### Advanced Application with Authentication
```python
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
from pydantic import BaseModel
from typing import Optional
import jwt
from datetime import datetime, timedelta
app = FastAPI()
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
class Token(BaseModel):
access_token: str
token_type: str
class User(BaseModel):
username: str
email: Optional[str] = None
full_name: Optional[str] = None
disabled: Optional[bool] = None
def verify_token(token: str = Depends(oauth2_scheme)):
try:
payload = jwt.decode(token, "secret", algorithms=["HS256"])
username: str = payload.get("sub")
if username is None:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Could not validate credentials",
headers={"WWW-Authenticate": "Bearer"},
)
return username
except jwt.PyJWTError:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Could not validate credentials",
headers={"WWW-Authenticate": "Bearer"},
)
@app.post("/token", response_model=Token)
async def login(form_data: OAuth2PasswordRequestForm = Depends()):
# Authenticate user (simplified)
if form_data.username == "testuser" and form_data.password == "testpass":
access_token_expires = timedelta(minutes=30)
access_token = jwt.encode(
{"sub": form_data.username, "exp": datetime.utcnow() + access_token_expires},
"secret",
algorithm="HS256"
)
return {"access_token": access_token, "token_type": "bearer"}
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Incorrect username or password",
headers={"WWW-Authenticate": "Bearer"},
)
@app.get("/users/me", response_model=User)
async def read_users_me(current_user: str = Depends(verify_token)):
return User(username=current_user, email="test@example.com")
@app.get("/protected")
async def protected_route(current_user: str = Depends(verify_token)):
return {"message": f"Hello {current_user}, this is a protected route"}
```
### File Upload Example
```python
from fastapi import FastAPI, File, UploadFile, Form
from typing import List
import shutil
app = FastAPI()
@app.post("/upload-file/")
async def upload_file(file: UploadFile = File(...)):
with open(f"uploads/{file.filename}", "wb") as buffer:
shutil.copyfileobj(file.file, buffer)
return {"filename": file.filename, "content_type": file.content_type}
@app.post("/upload-files/")
async def upload_files(files: List[UploadFile] = File(...)):
filenames = []
for file in files:
with open(f"uploads/{file.filename}", "wb") as buffer:
shutil.copyfileobj(file.file, buffer)
filenames.append(file.filename)
return {"filenames": filenames}
@app.post("/upload-with-form/")
async def upload_with_form(
file: UploadFile = File(...),
description: str = Form(...)
):
return {
"filename": file.filename,
"description": description,
"content_type": file.content_type
}
```
### WebSocket Chat Example
```python
from fastapi import FastAPI, WebSocket, WebSocketDisconnect
from typing import List
app = FastAPI()
class ConnectionManager:
def __init__(self):
self.active_connections: List[WebSocket] = []
async def connect(self, websocket: WebSocket):
await websocket.accept()
self.active_connections.append(websocket)
def disconnect(self, websocket: WebSocket):
self.active_connections.remove(websocket)
async def send_personal_message(self, message: str, websocket: WebSocket):
await websocket.send_text(message)
async def broadcast(self, message: str):
for connection in self.active_connections:
await connection.send_text(message)
manager = ConnectionManager()
@app.websocket("/ws/{client_id}")
async def websocket_endpoint(websocket: WebSocket, client_id: int):
await manager.connect(websocket)
try:
while True:
data = await websocket.receive_text()
await manager.send_personal_message(f"You wrote: {data}", websocket)
await manager.broadcast(f"Client #{client_id} says: {data}")
except WebSocketDisconnect:
manager.disconnect(websocket)
await manager.broadcast(f"Client #{client_id} left the chat")
```
## Running the Application
### Development Server
```bash
# Install uvicorn
pip install "uvicorn[standard]"
# Run the application
uvicorn main:app --reload
# Run with custom host and port
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```
### Production Deployment
```bash
# With Gunicorn
pip install gunicorn
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker
# With Docker
# Dockerfile
FROM python:3.9
WORKDIR /code
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80"]
```
## Key Import Statements Summary
```python
# Core FastAPI
from fastapi import (
FastAPI, APIRouter, Request, Response,
HTTPException, WebSocketException,
Depends, Security, BackgroundTasks,
status
)
# Parameter functions
from fastapi import (
Path, Query, Body, Header, Cookie,
Form, File, UploadFile
)
# WebSocket support
from fastapi import WebSocket, WebSocketDisconnect
from fastapi.websockets import WebSocketState
# Security
from fastapi.security import (
HTTPBasic, HTTPBearer, HTTPDigest,
OAuth2PasswordBearer, OAuth2AuthorizationCodeBearer,
OAuth2PasswordRequestForm, SecurityScopes,
APIKeyQuery, APIKeyHeader, APIKeyCookie
)
# Responses
from fastapi.responses import (
JSONResponse, HTMLResponse, PlainTextResponse,
RedirectResponse, StreamingResponse, FileResponse,
UJSONResponse, ORJSONResponse
)
# Middleware
from fastapi.middleware.cors import CORSMiddleware
from fastapi.middleware.gzip import GZipMiddleware
from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware
from fastapi.middleware.trustedhost import TrustedHostMiddleware
# Testing
from fastapi.testclient import TestClient
# Utilities
from fastapi.encoders import jsonable_encoder
from fastapi.staticfiles import StaticFiles
```
This documentation covers the complete FastAPI API for building modern, fast web APIs with Python. FastAPI provides automatic API documentation, request/response validation, dependency injection, security, and high performance through async support.
Loading…
Cancel
Save