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:
1 parent
dc463b3bfa
commit
164326ce76
4 files changed
+188
-5
No files matched your search
+132
@@ -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"
|
||||
}
|
||||
```
|
||||
Reference in new issue
Block a user