🎈 perf: update OpenAPI doc, remove unused import, fix #1

Author: SerinaNya

pastemc/main.py

@@ -9,6 +9,7 @@
 
 class AppInfo(BaseModel):
     title: str = __package__
+    description: str = "paste, share, even analyze: The pastebin design for Minecraft"
     version: str = metadata.version(__package__)
     license_info: dict = {
         "name": "GNU Affero General Public License v3.0 or later",

pastemc/models/common.py

@@ -1,17 +1,22 @@
 from datetime import datetime
-from importlib import metadata
 from typing import Annotated
 
 from annotated_types import Len
-from pydantic import AnyHttpUrl, BaseModel, BeforeValidator, Field, computed_field
+from pydantic import (
+    AnyHttpUrl,
+    BaseModel,
+    BeforeValidator,
+    Field,
+    validate_call,
+)
 from ulid import ULID
 
 from pastemc.utils.s3api import get_object_url
 
 FileId = Annotated[
     str,
     BeforeValidator(lambda v: str(v)),
-    Len(26),
+    Len(26, 26),
     Field(
         examples=["01HRKVWPKNYNQKB5F209DZ85B7"], description="ULID of the uploaded file"
     ),
@@ -41,10 +46,15 @@ class FileObjectResponse(BaseModel):
     file_id: FileId
     url: FileUrl
     last_modified: Annotated[
-        datetime, Field(examples=["2024-03-10T17:42:50.229000+08:00"])
+        datetime,
+        Field(
+            examples=["2024-03-10T17:42:50.229000+08:00"],
+            description="ISO 8601 datetime with server timezone",
+        ),
     ]
 
     @classmethod
+    @validate_call
     def public(cls, file_id: FileId):
         return cls(
             file_id=file_id,

pastemc/modules/fetch.py

@@ -1,8 +1,7 @@
 from typing import Annotated
 
 from annotated_types import Len
-from fastapi import APIRouter, status
-from fastapi.responses import JSONResponse
+from fastapi import APIRouter, Path, Response, status
 
 from pastemc.models.common import FileObjectResponse, ObjectNotFound
 from pastemc.utils.s3api import list_objects
@@ -16,13 +15,22 @@
     summary="Get File URL by file_id",
     responses={404: {"model": ObjectNotFound}},
 )
-async def fetch_file(file_id: Annotated[str, Len(10, 26)]):
+async def fetch_file(
+    response: Response,
+    file_id: Annotated[
+        str,
+        Len(10, 26),
+        Path(
+            description="this field accepts:\n- full ULID (26 digits)\n- partial ULID, with timestamp (at least 10 digits)",
+            examples=["01HRKVWPKNYNQKB5F209DZ85B7", "01HRKVWPKN"],
+        ),
+    ],
+):
     if len(file_id) == 26:  # full ULID
         return FileObjectResponse.public(file_id=file_id)
-    else:  # partial ULID, with timestamp (1-10 digits)
+    else:  # partial ULID, with timestamp (at least 10 digits)
         if objects_list := await list_objects(prefix=file_id):
             return FileObjectResponse.public(file_id=objects_list[0].object_name)
         else:
-            return JSONResponse(
-                ObjectNotFound.make(file_id), status_code=status.HTTP_404_NOT_FOUND
-            )
+            response.code = status.HTTP_404_NOT_FOUND
+            return ObjectNotFound.make(file_id)

pastemc/modules/upload.py

@@ -1,5 +1,4 @@
-from fastapi import APIRouter, File, Form, UploadFile, status
-from fastapi.responses import JSONResponse
+from fastapi import APIRouter, File, Form, Response, UploadFile, status
 from loguru import logger
 
 from pastemc.models.common import FileObjectResponse
@@ -16,7 +15,6 @@
     responses={
         201: {
             "model": FileObjectResponse,
-            "description": "`file_id` of the uploaded file",
             "headers": {
                 "Location": {
                     "$ref": "#/components/schemas/FileObjectResponse/properties/url"
@@ -26,6 +24,7 @@
     },
 )
 async def upload_file(
+    response: Response,
     file: UploadFile = File(description="the (Minecraft log) file"),
     format_type: str = Form(
         description="the format of this file, used for highlight rendering"
@@ -51,8 +50,6 @@ async def upload_file(
     logger.info(f"file uploaded, {file.filename=}, {file_id=}, {length=}")
 
     # return 201 created
-    return JSONResponse(
-        FileObjectResponse.public(file_id=file_id).model_dump(),
-        status_code=status.HTTP_201_CREATED,
-        headers={"Location": get_object_url(file_id)},
-    )
+    response.status_code = status.HTTP_201_CREATED
+    response.headers["Location"] = get_object_url(file_id)
+    return FileObjectResponse.public(file_id=file_id)