hertz_django_studio/hertz_django

Fork 0

Files

pony 638e152cff 上传规范文档

2025-11-17 16:39:30 +08:00

10 KiB

Raw Blame History

Hertz Studio Django Wiki 接口文档

基础路径: /api/wiki/
统一响应: 使用 HertzResponse，结构如下（参考 hertz_studio_django_utils/responses/HertzResponse.py）
```
{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": {}
}
```
路由挂载: 项目主路由中已通过 path('api/wiki/', include('hertz_studio_django_wiki.urls')) 挂载（hertz_server_django/urls.py:29）。
认证说明: 标注“需要登录”的接口需在请求头携带 Authorization: Bearer <token>（hertz_studio_django_auth/utils/decorators/auth_decorators.py:1）。

一、知识分类管理

（1）获取分类列表

方法: GET
路径: /api/wiki/categories/
认证: 不需要
查询参数:
- page: 页码，默认 1
- page_size: 每页数量，默认 10
- name: 分类名称关键字
- parent_id: 父分类ID（0 表示顶级）
- is_active: true/false
实现: wiki_category_list（hertz_studio_django_wiki/views.py:41）

请求示例:

curl "http://localhost:8000/api/wiki/categories/?page=1&page_size=10&name=技术"

返回示例:

{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": {
    "list": [
      {
        "id": 1,
        "name": "技术文档",
        "description": "技术相关文档",
        "parent": null,
        "parent_name": null,
        "sort_order": 1,
        "is_active": true,
        "created_at": "2024-01-01T10:00:00Z",
        "updated_at": "2024-01-01T10:00:00Z",
        "children_count": 3,
        "articles_count": 15,
        "full_path": "技术文档"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 10
  }
}

（2）获取树形分类

方法: GET
路径: /api/wiki/categories/tree/
认证: 不需要
实现: wiki_category_tree（hertz_studio_django_wiki/views.py:101）

请求示例:

curl "http://localhost:8000/api/wiki/categories/tree/"

返回示例:

[
  {
    "id": 1,
    "name": "技术文档",
    "description": "技术相关文档",
    "sort_order": 1,
    "is_active": true,
    "articles_count": 15,
    "children": [
      {"id": 2, "name": "后端", "children": []}
    ]
  }
]

（3）创建分类

方法: POST
路径: /api/wiki/categories/create/
认证: 不需要
请求体: application/json
字段: name, description, parent, sort_order, is_active
实现: wiki_category_create（hertz_studio_django_wiki/views.py:136）

请求示例:

POST /api/wiki/categories/create/
Content-Type: application/json

{
  "name": "新分类",
  "description": "分类描述",
  "parent": null,
  "sort_order": 10,
  "is_active": true
}

返回示例:

{
  "success": true,
  "code": 200,
  "message": "知识分类创建成功",
  "data": {
    "id": 5,
    "name": "新分类",
    "description": "分类描述",
    "parent": null,
    "parent_name": null,
    "sort_order": 10,
    "is_active": true,
    "created_at": "2025-11-17T10:00:00Z",
    "updated_at": "2025-11-17T10:00:00Z",
    "children_count": 0,
    "articles_count": 0,
    "full_path": "新分类"
  }
}

（4）分类详情

方法: GET
路径: /api/wiki/categories/{category_id}/
认证: 不需要
实现: wiki_category_detail（hertz_studio_django_wiki/views.py:178）

请求示例:

curl "http://localhost:8000/api/wiki/categories/1/"

返回示例: 同“获取分类列表”中的单项结构。

（5）更新分类

方法: PUT（支持部分更新）
路径: /api/wiki/categories/{category_id}/update/
认证: 不需要
请求体: application/json
可更新字段: name, description, parent, sort_order, is_active
实现: wiki_category_update（hertz_studio_django_wiki/views.py:220）

请求示例:

PUT /api/wiki/categories/1/update/
Content-Type: application/json

{
  "name": "更新后的分类名",
  "description": "更新后的描述",
  "sort_order": 20
}

返回示例:

{"success": true, "code": 200, "message": "知识分类更新成功", "data": {"id": 1, "name": "更新后的分类名"}}

（6）删除分类

方法: DELETE
路径: /api/wiki/categories/{category_id}/delete/
认证: 不需要
行为: 软删除（将 is_active=false）；若存在子分类或文章将返回错误
实现: wiki_category_delete（hertz_studio_django_wiki/views.py:270）

请求示例:

curl -X DELETE "http://localhost:8000/api/wiki/categories/1/delete/"

返回示例:

{"success": true, "code": 200, "message": "知识分类删除成功"}

二、知识文章管理

（1）获取文章列表

方法: GET
路径: /api/wiki/articles/
认证: 不需要
查询参数:
- page, page_size
- title: 标题关键字
- category_id: 分类ID
- author_id: 作者ID
- status: draft|published|archived
实现: wiki_article_list（hertz_studio_django_wiki/views.py:318）

请求示例:

curl "http://localhost:8000/api/wiki/articles/?page=1&page_size=10&category_id=1&status=published"

返回示例:

{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": {
    "list": [
      {
        "id": 101,
        "title": "如何部署Django",
        "summary": "部署流程概览",
        "image": null,
        "category_name": "技术文档",
        "author_name": "alice",
        "status": "published",
        "status_display": "已发布",
        "view_count": 42,
        "created_at": "2025-11-01T09:00:00Z",
        "updated_at": "2025-11-10T09:00:00Z",
        "published_at": "2025-11-10T09:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 10
  }
}

（2）创建文章（需要登录）

方法: POST
路径: /api/wiki/articles/create/
认证: 需要登录（Authorization: Bearer <token>）
请求体: application/json
字段: title, content, summary, image, category, status, tags, sort_order
实现: wiki_article_create（hertz_studio_django_wiki/views.py:384）

请求示例:

POST /api/wiki/articles/create/
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "新文章",
  "content": "文章内容...",
  "summary": "文章摘要...",
  "image": null,
  "category": 1,
  "status": "draft",
  "tags": "django,部署",
  "sort_order": 10
}

返回示例:

{
  "success": true,
  "code": 200,
  "message": "知识文章创建成功",
  "data": {
    "id": 102,
    "title": "新文章",
    "content": "文章内容...",
    "summary": "文章摘要...",
    "image": null,
    "category": 1,
    "category_name": "技术文档",
    "author": 2,
    "author_name": "alice",
    "status": "draft",
    "status_display": "草稿",
    "tags": "django,部署",
    "tags_list": ["django", "部署"],
    "view_count": 0,
    "sort_order": 10,
    "created_at": "2025-11-17T11:00:00Z",
    "updated_at": "2025-11-17T11:00:00Z",
    "published_at": null
  }
}

（3）文章详情

方法: GET
路径: /api/wiki/articles/{article_id}/
认证: 不需要
行为: 获取详情并增加浏览量
实现: wiki_article_detail（hertz_studio_django_wiki/views.py:426）

请求示例:

curl "http://localhost:8000/api/wiki/articles/102/"

返回示例: 同“创建文章”中的完整字段结构，view_count 将递增。

（4）更新文章

方法: PUT（支持部分更新）
路径: /api/wiki/articles/{article_id}/update/
认证: 不需要
请求体: application/json
可更新字段: title, content, summary, image, category, status, tags, sort_order
实现: wiki_article_update（hertz_studio_django_wiki/views.py:472）

请求示例:

PUT /api/wiki/articles/102/update/
Content-Type: application/json

{
  "status": "published",
  "summary": "更新后的摘要"
}

返回示例:

{"success": true, "code": 200, "message": "知识文章更新成功", "data": {"id": 102, "status": "published"}}

（5）删除文章

方法: DELETE
路径: /api/wiki/articles/{article_id}/delete/
认证: 不需要
实现: wiki_article_delete（hertz_studio_django_wiki/views.py:518）

请求示例:

curl -X DELETE "http://localhost:8000/api/wiki/articles/102/delete/"

返回示例:

{"success": true, "code": 200, "message": "知识文章删除成功"}

（6）发布文章

方法: POST
路径: /api/wiki/articles/{article_id}/publish/
认证: 不需要
实现: wiki_article_publish（hertz_studio_django_wiki/views.py:561）

请求示例:

curl -X POST "http://localhost:8000/api/wiki/articles/102/publish/"

返回示例:

{"success": true, "code": 200, "message": "知识文章发布成功"}

失败示例（已发布再次发布）:

{"success": false, "code": 500, "message": "系统错误", "error": "文章已经是发布状态"}

（7）归档文章

方法: POST
路径: /api/wiki/articles/{article_id}/archive/
认证: 不需要
实现: wiki_article_archive（hertz_studio_django_wiki/views.py:609）

请求示例:

curl -X POST "http://localhost:8000/api/wiki/articles/102/archive/"

返回示例:

{"success": true, "code": 200, "message": "知识文章归档成功"}

三、备注

文章状态枚举: draft|published|archived（hertz_studio_django_wiki/models.py:35）。
分类软删除通过 is_active=false 实现；删除校验会阻止删除存在子分类或文章的分类（views.py:270）。
文章详情接口会递增 view_count（hertz_studio_django_wiki/models.py:70 和 views.py:431）。

10 KiB Raw Blame History Unescape Escape

Hertz Studio Django Wiki 接口文档

一、知识分类管理

（1）获取分类列表

（2）获取树形分类

（3）创建分类

（4）分类详情

（5）更新分类

（6）删除分类

二、知识文章管理

（1）获取文章列表

（2）创建文章（需要登录）

（3）文章详情

（4）更新文章

（5）删除文章

（6）发布文章

（7）归档文章

三、备注

10 KiB

Raw Blame History