81632c1b35
- 添加架构文档 (ARCHITECTURE.md) - 添加 API 文档 (API.md) - 添加文档索引 (docs/README.md) - 添加部署技能 (skills/city-manual-deploy/SKILL.md) - 添加测试技能 (skills/city-manual-test/SKILL.md) - 添加内容管理技能 (skills/city-manual-content/SKILL.md)
7.9 KiB
7.9 KiB
城市手册 - API 文档
1. API 概述
1.1 基础信息
- Base URL:
http://localhost:8000/api - 认证方式: JWT Bearer Token
- 数据格式: JSON
- GraphQL 端点:
http://localhost:8000/graphql/
1.2 认证
所有需要认证的接口需要在 Header 中携带 JWT Token：
Authorization: Bearer <access_token>
1.3 错误响应
{
"error": {
"code": "ERROR_CODE",
"message": "错误描述",
"details": {}
}
}
2. 用户认证 API
2.1 用户注册
POST /api/users/
请求：
{
"username": "string",
"email": "string",
"password": "string",
"phone": "string"
}
响应：
{
"id": 1,
"username": "string",
"email": "string",
"phone": "string",
"role": "user",
"created_at": "2026-04-12T00:00:00Z"
}
2.2 用户登录
POST /api/auth/token/
请求：
{
"username": "string",
"password": "string"
}
响应：
{
"access": "eyJ0eXAiOiJKV1QiLCJhbGc...",
"refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}
2.3 刷新令牌
POST /api/auth/token/refresh/
请求：
{
"refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}
响应：
{
"access": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}
2.4 获取当前用户信息
GET /api/users/me/
Headers:
Authorization: Bearer <access_token>
响应：
{
"id": 1,
"username": "string",
"email": "string",
"phone": "string",
"role": "user",
"avatar": "url",
"created_at": "2026-04-12T00:00:00Z"
}
2.5 更新用户信息
PUT /api/users/me/
请求：
{
"username": "string",
"email": "string",
"phone": "string",
"avatar": "url"
}
3. 版块管理 API
3.1 获取版块列表
GET /api/regions/
查询参数：
level- 版块级别（province/city/county/town/village）parent- 上级版块 IDsearch- 搜索关键词
响应：
{
"count": 100,
"next": "url",
"previous": "url",
"results": [
{
"id": 1,
"name": "广东省",
"level": "province",
"parent": null,
"children": [],
"moderator_count": 5,
"article_count": 100
}
]
}
3.2 获取版块详情
GET /api/regions/{id}/
响应：
{
"id": 1,
"name": "深圳市",
"level": "city",
"parent": {
"id": 1,
"name": "广东省"
},
"children": [
{"id": 2, "name": "南山区"},
{"id": 3, "name": "福田区"}
],
"description": "description",
"moderator_count": 3,
"article_count": 50,
"service_count": 20,
"created_at": "2026-04-12T00:00:00Z"
}
3.3 创建版块
POST /api/regions/
权限： 管理员
请求：
{
"name": "string",
"level": "city",
"parent": 1,
"description": "string"
}
4. 内容管理 API
4.1 获取文章列表
GET /api/articles/
查询参数：
region- 版块 IDcategory- 分类（history/culture/practical/life）status- 状态（draft/pending/published/rejected）search- 搜索关键词
响应：
{
"count": 100,
"results": [
{
"id": 1,
"title": "深圳历史",
"region": {"id": 1, "name": "深圳市"},
"category": "history",
"author": {"id": 1, "username": "author"},
"status": "published",
"view_count": 1000,
"like_count": 50,
"comment_count": 10,
"created_at": "2026-04-12T00:00:00Z",
"updated_at": "2026-04-12T00:00:00Z"
}
]
}
4.2 获取文章详情
GET /api/articles/{id}/
响应：
{
"id": 1,
"title": "深圳历史",
"content": "markdown content",
"region": {"id": 1, "name": "深圳市"},
"category": "history",
"author": {"id": 1, "username": "author"},
"status": "published",
"view_count": 1000,
"like_count": 50,
"comment_count": 10,
"tags": ["历史", "文化"],
"created_at": "2026-04-12T00:00:00Z",
"updated_at": "2026-04-12T00:00:00Z"
}
4.3 创建文章
POST /api/articles/
权限： 认证用户
请求：
{
"title": "string",
"content": "markdown content",
"region": 1,
"category": "history",
"tags": ["tag1", "tag2"]
}
4.4 更新文章
PUT /api/articles/{id}/
权限： 作者或版主或管理员
请求：
{
"title": "string",
"content": "markdown content",
"category": "history",
"tags": ["tag1", "tag2"]
}
4.5 删除文章
DELETE /api/articles/{id}/
权限： 作者或版主或管理员
5. 特色服务 API
5.1 获取特色服务列表
GET /api/services/
查询参数：
region- 版块 IDcategory- 分类（clothing/food/accommodation/transportation/entertainment/tourism/culture）status- 状态
响应：
{
"count": 100,
"results": [
{
"id": 1,
"name": "深圳湾公园",
"region": {"id": 1, "name": "深圳市"},
"category": "tourism",
"description": "description",
"rating": 4.5,
"rating_count": 100,
"status": "published",
"created_at": "2026-04-12T00:00:00Z"
}
]
}
5.2 获取特色服务详情
GET /api/services/{id}/
响应：
{
"id": 1,
"name": "深圳湾公园",
"description": "description",
"region": {"id": 1, "name": "深圳市"},
"category": "tourism",
"address": "地址",
"contact": "联系方式",
"images": ["url1", "url2"],
"rating": 4.5,
"rating_count": 100,
"status": "published",
"author": {"id": 1, "username": "author"},
"created_at": "2026-04-12T00:00:00Z"
}
5.3 创建特色服务
POST /api/services/
请求：
{
"name": "string",
"description": "string",
"region": 1,
"category": "tourism",
"address": "string",
"contact": "string",
"images": ["url1", "url2"]
}
6. 互动功能 API
6.1 评论
GET /api/comments/
查询参数：
object_type- 对象类型（article/service）object_id- 对象 ID
POST /api/comments/
请求：
{
"content": "string",
"object_type": "article",
"object_id": 1
}
6.2 评分
POST /api/ratings/
请求：
{
"score": 5,
"object_type": "service",
"object_id": 1
}
6.3 点赞
POST /api/likes/
请求：
{
"object_type": "article",
"object_id": 1
}
6.4 收藏
POST /api/favorites/
请求：
{
"object_type": "region",
"object_id": 1
}
GET /api/favorites/
获取当前用户的收藏列表
7. 版主管理 API
7.1 申请版主
POST /api/moderator-applications/
请求：
{
"region": 1,
"reason": "申请理由"
}
7.2 获取版主申请列表
GET /api/moderator-applications/
权限： 管理员
7.3 审核版主申请
POST /api/moderator-applications/{id}/review/
权限： 管理员
请求：
{
"status": "approved",
"reason": "审核意见"
}
7.4 获取版主权限
GET /api/moderator-permissions/
权限： 版主
8. GraphQL API
8.1 查询示例
query {
region(id: 1) {
id
name
level
children {
id
name
}
articles {
id
title
author {
username
}
}
}
}
8.2 变更示例
mutation {
createArticle(input: {
title: "深圳历史"
content: "内容"
region: 1
category: HISTORY
}) {
article {
id
title
status
}
}
}
9. 错误码
| 错误码 | 说明 |
|---|---|
AUTH_FAILED |
认证失败 |
PERMISSION_DENIED |
权限不足 |
NOT_FOUND |
资源不存在 |
VALIDATION_ERROR |
参数验证错误 |
DUPLICATE |
重复资源 |
INVALID_STATUS |
无效状态 |
10. 速率限制
- 未认证用户：100 请求/小时
- 认证用户：1000 请求/小时
- 管理员：无限制
11. 版本控制
当前 API 版本：v1
版本格式：/api/v1/