feat:更新路由注释

2025-12-11 14:02:39 +08:00
parent 49d634b877
commit 5462ecc8af
2 changed files with 80 additions and 49 deletions
--- a/api/blog.py
+++ b/api/blog.py
@@ -1,6 +1,6 @@
 from typing import List

-from fastapi import APIRouter, Depends, Query, Request, UploadFile, File
+from fastapi import APIRouter, Depends, Query, Request, UploadFile, File, Path, Body
 from sqlalchemy.orm import Session

 from config.auth import verify_token
@@ -20,7 +20,8 @@ router = APIRouter(


@router.post("/file/upload", summary="上传博客图片", response_model=str)
-async def sync_all_blog(md5: str, file: UploadFile = File(...)):
+async def sync_all_blog(md5: str = Query(..., description="文件MD5值"),
+                        file: UploadFile = File(..., description="要上传的图片文件")):
    return await file_service.upload_file(md5, file)


@@ -30,28 +31,31 @@ def sync_all_blog(db: Session = Depends(get_db)):


@router.get("/search", summary="搜索elastic", response_model=List[BlogSearch])
-def search_blog(keyword: str):
+def search_blog(keyword: str = Query(..., description="搜索关键词")):
    return blog_elastic_service.search_blog(keyword)


@router.get("/page", summary="分页查询博客", response_model=PageResult[BlogResponse])
-def query_blog_by_page(current_page: int = Query(1, ge=1, alias="currentPage", description="当前页码"),
-                       page_size: int = Query(10, ge=1, le=100, alias="pageSize", description="每页数量"),
-                       db: Session = Depends(get_db)):
+def query_blog_by_page(
+        current_page: int = Query(1, ge=1, alias="currentPage", description="当前页码，从1开始"),
+        page_size: int = Query(10, ge=1, le=100, alias="pageSize", description="每页显示数量，1-100之间"),
+        db: Session = Depends(get_db)
+):
    return blog_service.query_blog_by_page(db, current_page, page_size)


@router.get("/condition", summary="条件查询博客", response_model=List[BlogResponse])
-def query_blog_by_condition(query: BlogQuery = Depends(),
-                            db: Session = Depends(get_db)):
+def query_blog_by_condition(query: BlogQuery = Depends(), db: Session = Depends(get_db)):
    return blog_service.query_blog_by_condition(db, query)


@router.get("/condition/page", summary="条件分页查询博客", response_model=PageResult[BlogResponse])
-def query_blog_by_condition_page(query: BlogQuery = Depends(),
-                                 current_page: int = Query(1, ge=1, alias="currentPage", description="当前页码"),
-                                 page_size: int = Query(10, ge=1, le=100, alias="pageSize", description="每页数量"),
-                                 db: Session = Depends(get_db)):
+def query_blog_by_condition_page(
+        query: BlogQuery = Depends(),
+        current_page: int = Query(1, ge=1, alias="currentPage", description="当前页码，从1开始"),
+        page_size: int = Query(10, ge=1, le=100, alias="pageSize", description="每页显示数量，1-100之间"),
+        db: Session = Depends(get_db)
+):
    return blog_service.query_blog_by_condition_page(db, query, current_page, page_size)


@@ -61,44 +65,65 @@ def query_unapproved_blog(db: Session = Depends(get_db), _=Depends(verify_token)


@router.get("/{blog_id}/content", summary="查询博客内容", response_model=BlogResponse)
-def query_blog_by_id(blog_id: int, db: Session = Depends(get_db)):
+def query_blog_by_id(blog_id: int = Path(..., ge=1, description="博客ID"), db: Session = Depends(get_db)):
    return blog_service.query_blog_by_id(db, blog_id)


@router.get("/all/page", summary="分页查询博客", response_model=PageResult[BlogResponse])
-def query_blog_by_page(current_page: int = Query(1, ge=1, alias="currentPage", description="当前页码"),
-                       page_size: int = Query(10, ge=1, le=100, alias="pageSize", description="每页数量"),
-                       db: Session = Depends(get_db), _=Depends(verify_token)):
+def query_blog_by_page(
+        current_page: int = Query(1, ge=1, alias="currentPage", description="当前页码，从1开始"),
+        page_size: int = Query(10, ge=1, le=100, alias="pageSize", description="每页显示数量，1-100之间"),
+        db: Session = Depends(get_db),
+        _=Depends(verify_token)
+):
    return blog_service.query_blog_by_page(db, current_page, page_size, True)


@router.post("", summary="新增博客内容", response_model=bool)
-def add_blog(blog: BlogCreate, db: Session = Depends(get_db), _=Depends(verify_token)):
+def add_blog(
+        blog: BlogCreate = Body(..., description="博客创建数据"),
+        db: Session = Depends(get_db),
+        _=Depends(verify_token)
+):
    return blog_service.add_blog(db, blog)


@router.put("/{blog_id}", summary="更新博客内容", response_model=bool)
-def update_blog(blog_id: int, blog: BlogUpdate, db: Session = Depends(get_db), _=Depends(verify_token)):
+def update_blog(
+        blog_id: int = Path(..., ge=1, description="博客ID"),
+        blog: BlogUpdate = Body(..., description="博客更新数据"),
+        db: Session = Depends(get_db),
+        _=Depends(verify_token)
+):
    return blog_service.update_blog(db, blog_id, blog)


@router.delete("/{blog_id}", summary="删除博客内容", response_model=bool)
-def delete_blog(blog_id: int, db: Session = Depends(get_db), _=Depends(verify_token)):
+def delete_blog(
+        blog_id: int = Path(..., ge=1, description="博客ID"),
+        db: Session = Depends(get_db),
+        _=Depends(verify_token)
+):
    return blog_service.delete_blog(db, blog_id)


@router.get("/{blog_id}/adjacent", summary="查询相邻博客", response_model=List[BlogAdjacentResponse])
-def query_blog_latest(blog_id: int, db: Session = Depends(get_db)):
+def query_blog_latest(blog_id: int = Path(..., ge=1, description="博客ID"), db: Session = Depends(get_db)):
    return blog_service.query_blog_adjacent(db, blog_id)


@router.put("/{blog_id}/comment", summary="新增博客评论", response_model=bool)
-def add_blog_comment(blog_id: int, blog_comment: BlogCommentCreate, request: Request, db: Session = Depends(get_db)):
+def add_blog_comment(
+        request: Request,
+        blog_id: int = Path(..., ge=1, description="博客ID"),
+        blog_comment: BlogCommentCreate = Body(..., description="博客评论数据"),
+        db: Session = Depends(get_db)
+):
    return blog_service.add_blog_comment(db, request, blog_id, blog_comment)


@router.get("/{blog_id}/comment", summary="查询博客评论", response_model=list[BlogCommentResponse])
-def query_blog_comment(blog_id: int, db: Session = Depends(get_db)):
+def query_blog_comment(blog_id: int = Path(..., ge=1, description="博客ID"), db: Session = Depends(get_db)):
    return blog_service.query_blog_comment(db, blog_id)


@@ -113,9 +138,11 @@ def query_blog_stats(db: Session = Depends(get_db)):


@router.get("/visit", summary="查询博客访问信息", response_model=PageResult[BlogVisitResponse])
-def query_blog_visit(current_page: int = Query(1, ge=1, alias="currentPage", description="当前页码"),
-                     page_size: int = Query(10, ge=1, le=100, alias="pageSize", description="每页数量"),
-                     db: Session = Depends(get_db)):
+def query_blog_visit(
+        current_page: int = Query(1, ge=1, alias="currentPage", description="当前页码，从1开始"),
+        page_size: int = Query(10, ge=1, le=100, alias="pageSize", description="每页显示数量，1-100之间"),
+        db: Session = Depends(get_db)
+):
    return blog_service.query_blog_visit(db, current_page, page_size)


--- a/schemas/blog.py
+++ b/schemas/blog.py
@@ -1,6 +1,6 @@
 from typing import Optional

-from pydantic import BaseModel, Field, field_validator
+from pydantic import BaseModel, Field, field_validator, ConfigDict
 from datetime import datetime


@@ -56,22 +56,23 @@ class BlogResponse(BlogBase):
    create_time: datetime = Field(..., description="创建时间", alias="createTime")
    update_time: datetime = Field(..., description="更新时间", alias="updateTime")

-    class Config:
-        from_attributes = True
-        populate_by_name = True
-        json_encoders = {
-            # 自定义 datetime 类型的序列化格式
+    model_config = ConfigDict(
+        from_attributes=True,
+        populate_by_name=True,
+        json_encoders={
            datetime: lambda dt: dt.strftime('%Y-%m-%d %H:%M:%S')
        }
+    )


 class BlogCategoryResponse(BaseModel):
    name: str = Field(..., description="分类名称")
    count: int = Field(..., description="博客数量")

-    class Config:
-        from_attributes = True
-        populate_by_name = True
+    model_config = ConfigDict(
+        from_attributes=True,
+        populate_by_name=True
+    )


 class BlogStatsResponse(BaseModel):
@@ -88,30 +89,33 @@ class BlogVisitResponse(BaseModel):
    title: str = Field(None, description="博客标题")
    visit_time: datetime = Field(..., description="访问时间", alias="visitTime")

-    class Config:
-        from_attributes = True
-        populate_by_name = True
-        json_encoders = {
+    model_config = ConfigDict(
+        from_attributes=True,
+        populate_by_name=True,
+        json_encoders={
            datetime: lambda dt: dt.strftime('%Y-%m-%d %H:%M:%S')
        }
+    )


 class BlogLatestResponse(BaseModel):
    id: int = Field(..., description="博客ID")
    title: str = Field(..., description="博客标题")

-    class Config:
-        from_attributes = True
-        populate_by_name = True
+    model_config = ConfigDict(
+        from_attributes=True,
+        populate_by_name=True
+    )


 class BlogAdjacentResponse(BaseModel):
    id: int = Field(..., description="博客ID")
    title: str = Field(..., description="博客标题")

-    class Config:
-        from_attributes = True
-        populate_by_name = True
+    model_config = ConfigDict(
+        from_attributes=True,
+        populate_by_name=True
+    )


 class BlogCommentCreate(BaseModel):
@@ -139,10 +143,10 @@ class BlogCommentResponse(BlogCommentCreate):
    user_agent: str = Field(..., description="浏览器信息", alias="userAgent")
    create_time: datetime = Field(..., description="创建时间", alias="createTime")

-    class Config:
-        from_attributes = True
-        populate_by_name = True
-        json_encoders = {
-            # 自定义 datetime 类型的序列化格式
+    model_config = ConfigDict(
+        from_attributes=True,
+        populate_by_name=True,
+        json_encoders={
            datetime: lambda dt: dt.strftime('%Y-%m-%d %H:%M:%S')
        }
+    )