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

+132
View File
@@ -0,0 +1,132 @@
# API 设计文档
版本:1.0.0
更新日期:2026-05-07
## 概述
本 API 提供简单的 CRUD 操作,用于管理项目(Item)。
## 基础信息
- 基础 URL: `http://localhost:8000`
- 内容类型: `application/json`
- 认证: 无
## 端点
### 健康检查
```
GET /health
```
**响应示例:**
```json
{
"status": "ok"
}
```
---
### 创建项目
```
POST /items
```
**请求体:**
```json
{
"name": "string (必填)",
"description": "string (可选)"
}
```
**响应示例:**
```json
{
"id": 1,
"name": "My Item",
"description": "A test item"
}
```
**状态码:**
- 200: 创建成功
---
### 列出项目
```
GET /items
```
**响应示例:**
```json
[
{
"id": 1,
"name": "My Item",
"description": "A test item"
}
]
```
**状态码:**
- 200: 成功
---
### 获取单个项目
```
GET /items/{item_id}
```
**路径参数:**
- `item_id`: 项目 ID (integer)
**响应示例:**
```json
{
"id": 1,
"name": "My Item",
"description": "A test item"
}
```
**状态码:**
- 200: 成功
- 404: 项目不存在
---
## 错误响应
```json
{
"detail": "错误描述"
}
```
## 数据模型
### Item
```json
{
"id": "integer",
"name": "string",
"description": "string | null"
}
```
### ItemCreate
```json
{
"name": "string",
"description": "string | null"
}
```