feat:更新路由注释

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="当前页码"),
+def query_blog_by_page(
-                       page_size: int = Query(10, ge=1, le=100, alias="pageSize", description="每页数量"),
+        current_page: int = Query(1, ge=1, alias="currentPage", description="当前页码，从1开始"),
-                       db: Session = Depends(get_db)):
+        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(),
+def query_blog_by_condition(query: BlogQuery = Depends(), db: Session = Depends(get_db)):
-                            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(),
+def query_blog_by_condition_page(
-                                 current_page: int = Query(1, ge=1, alias="currentPage", description="当前页码"),
+        query: BlogQuery = Depends(),
-                                 page_size: int = Query(10, ge=1, le=100, alias="pageSize", description="每页数量"),
+        current_page: int = Query(1, ge=1, alias="currentPage", description="当前页码，从1开始"),
-                                 db: Session = Depends(get_db)):
+        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="当前页码"),
+def query_blog_by_page(
-                       page_size: int = Query(10, ge=1, le=100, alias="pageSize", description="每页数量"),
+        current_page: int = Query(1, ge=1, alias="currentPage", description="当前页码，从1开始"),
-                       db: Session = Depends(get_db), _=Depends(verify_token)):
+        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="当前页码"),
+def query_blog_visit(
-                     page_size: int = Query(10, ge=1, le=100, alias="pageSize", description="每页数量"),
+        current_page: int = Query(1, ge=1, alias="currentPage", description="当前页码，从1开始"),
-                     db: Session = Depends(get_db)):
+        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)
 
 

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:
+    model_config = ConfigDict(
-        from_attributes = True
+        from_attributes=True,
-        populate_by_name = True
+        populate_by_name=True,
-        json_encoders = {
+        json_encoders={
-            # 自定义 datetime 类型的序列化格式
             datetime: lambda dt: dt.strftime('%Y-%m-%d %H:%M:%S')
         }
+    )
 
 
 class BlogCategoryResponse(BaseModel):
     name: str = Field(..., description="分类名称")
     count: int = Field(..., description="博客数量")
 
-    class Config:
+    model_config = ConfigDict(
-        from_attributes = True
+        from_attributes=True,
-        populate_by_name = 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:
+    model_config = ConfigDict(
-        from_attributes = True
+        from_attributes=True,
-        populate_by_name = True
+        populate_by_name=True,
-        json_encoders = {
+        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:
+    model_config = ConfigDict(
-        from_attributes = True
+        from_attributes=True,
-        populate_by_name = True
+        populate_by_name=True
+    )
 
 
 class BlogAdjacentResponse(BaseModel):
     id: int = Field(..., description="博客ID")
     title: str = Field(..., description="博客标题")
 
-    class Config:
+    model_config = ConfigDict(
-        from_attributes = True
+        from_attributes=True,
-        populate_by_name = 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:
+    model_config = ConfigDict(
-        from_attributes = True
+        from_attributes=True,
-        populate_by_name = True
+        populate_by_name=True,
-        json_encoders = {
+        json_encoders={
-            # 自定义 datetime 类型的序列化格式
             datetime: lambda dt: dt.strftime('%Y-%m-%d %H:%M:%S')
         }
+    )