fastapi-crud-api/docs/API.md

# 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"
}
```