docs: add comprehensive documentation

- Add docstrings to models and main.py
- Create API.md with detailed endpoint documentation
- Create CHANGELOG.md for version tracking
- Enhance FastAPI app metadata (description, version, tags)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
rootandClaude Opus 4.7 committed 2026-05-07 08:35:44 +08:00
1 parent dc463b3bfa
commit 164326ce76
4 files changed
+188 -5

No files matched your search

+24 -5
View File
@@ -1,21 +1,31 @@
"""FastAPI 应用入口。
提供健康检查和项目 CRUD 端点。
"""
from fastapi import FastAPI, HTTPException
from typing import Dict
from app.models import Item, ItemCreate
app = FastAPI(title="FastAPI Example")
app = FastAPI(
title="FastAPI Example",
description="最小化 CRUD API 示例",
version="1.0.0"
)
# 内存存储
_items: Dict[int, Item] = {}
_item_id_counter = 0
@app.get("/health")
@app.get("/health", tags=["系统"])
async def health_check():
"""健康检查端点,返回服务状态。"""
return {"status": "ok"}
@app.post("/items", response_model=Item)
@app.post("/items", response_model=Item, tags=["项目"])
async def create_item(item: ItemCreate):
"""创建新项目。"""
global _item_id_counter
_item_id_counter += 1
new_item = Item(id=_item_id_counter, **item.model_dump())
@@ -23,13 +33,22 @@ async def create_item(item: ItemCreate):
return new_item
@app.get("/items", response_model=list[Item])
@app.get("/items", response_model=list[Item], tags=["项目"])
async def list_items():
"""列出所有项目。"""
return list(_items.values())
@app.get("/items/{item_id}", response_model=Item)
@app.get("/items/{item_id}", response_model=Item, tags=["项目"])
async def get_item(item_id: int):
"""获取单个项目。
Args:
item_id: 项目 ID
Raises:
HTTPException: 项目不存在时返回 404
"""
if item_id not in _items:
raise HTTPException(status_code=404, detail="Item not found")
return _items[item_id]
+6
View File
@@ -1,13 +1,19 @@
"""数据模型定义。
定义 API 请求和响应使用的 Pydantic 模型。
"""
from pydantic import BaseModel
from typing import Optional
class Item(BaseModel):
"""项目完整数据模型,包含 ID。"""
id: Optional[int] = None
name: str
description: Optional[str] = None
class ItemCreate(BaseModel):
"""创建项目的请求模型,不包含 ID。"""
name: str
description: Optional[str] = None