FastAPI 交互式 API 文档

from fastapi import FastAPI

app = FastAPI(
    title="🚀 我的电商 API",
    description="这是一个用于管理商品和用户的后端服务，基于 FastAPI 构建。",
    version="1.0.0",
    contact={
        "name": "开发团队",
        "email": "dev@example.com",
        "url": "https://example.com",
    },
    license_info={
        "name": "Apache 2.0",
        "url": "https://www.apache.org/licenses/LICENSE-2.0.html",
    },
    # 自定义文档路径 (可选)
    docs_url="/api-docs",      # 将 Swagger UI 改为 /api-docs
    redoc_url="/api-redoc",    # 将 ReDoc 改为 /api-redoc
    openapi_url="/openapi.json" # OpenAPI schema 的路径
)

@app.get("/")
def read_root():
    return {"message": "查看文档请访问 /api-docs"}

@app.get(
    "/items/{item_id}",
    summary="获取商品详情",
    description="""
    根据商品 ID 获取详细信息。

    - **item_id**: 必须是正整数。
    - 如果商品不存在，将返回 404 错误。
    - 支持通过 `q` 参数进行模糊搜索。
    """,
    tags=["商品管理"] # 用于在文档左侧对接口进行分组
)
def get_item(item_id: int, q: str | None = None):
    return {"item_id": item_id, "query": q}

from pydantic import BaseModel, Field

class UserCreate(BaseModel):
    username: str = Field(
        ..., 
        min_length=3, 
        max_length=50,
        description="用户的登录名",
        examples=["alice_2024", "bob_dev"]
    )
    email: str = Field(
        ..., 
        description="用户的电子邮箱",
        examples=["alice@example.com"]
    )
    age: int | None = Field(
        default=None, 
        ge=18, 
        description="用户年龄 (可选)",
        examples=[25, 30]
    )

@app.post("/users/", response_model=UserCreate, tags=["用户管理"])
def create_user(user: UserCreate):
    return user

from fastapi import HTTPException, status

@app.get(
    "/items/{item_id}",
    responses={
        404: {"description": "商品未找到"},
        400: {"description": "无效的 Item ID"}
    }
)
def get_item_detail(item_id: int):
    if item_id < 0:
        raise HTTPException(status_code=400, detail="无效的 Item ID")
    if item_id != 1:
        raise HTTPException(status_code=404, detail="商品未找到")
    return {"item_id": item_id, "name": "Laptop"}

from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials

app = FastAPI()
security = HTTPBearer()

def get_current_user(credentials: HTTPAuthorizationCredentials = Depends(security)):
    if credentials.credentials != "super-secret-token":
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="无效的 Token",
            headers={"WWW-Authenticate": "Bearer"},
        )
    return {"username": "admin"}

@app.get("/protected-data")
def protected_route(user: dict = Depends(get_current_user)):
    return {"message": f"欢迎, {user['username']}! 这是机密数据。"}

# 生产环境配置
app = FastAPI(
    docs_url=None,      # 禁用 Swagger UI
    redoc_url=None,     # 禁用 ReDoc
    openapi_url=None    # 禁用 OpenAPI schema 下载 (可选，但某些客户端可能依赖它)
)