docs: limit and offset

codeforjapan · Nov 1, 2024 · d049750 · d049750
1 parent d9ed588
commit d049750
Show file tree

Hide file tree

Showing 2 changed files with 88 additions and 4 deletions.
diff --git a/api/birdxplorer_api/openapi_doc.py b/api/birdxplorer_api/openapi_doc.py
@@ -128,6 +128,46 @@ class FastAPIEndpointDocs(Generic[_KEY]):
     },
 }
 
+v1_data_posts_offset: FastAPIEndpointParamDocs = {
+    "description": """
+取得する Post のリストの先頭からのオフセット。ページネーションに利用される。
+
+
+ただし、レスポンスの `meta.next` や `meta.prev` で次のページや前のページのリクエスト用 URL が提供されるため、
+そちらを利用したほうが良い場合もある。
+""",
+    "openapi_examples": {
+        "default": {
+            "summary": "0 (デフォルト)",
+            "value": 0,
+        },
+        "offset_100": {
+            "summary": "100",
+            "value": 100,
+        },
+    },
+}
+
+v1_data_posts_limit: FastAPIEndpointParamDocs = {
+    "description": """
+取得する Post のリストの最大数。 0 ～ 1000 まで指定できる。ページネーションに利用される。
+
+
+ただし、 `meta.next` や `meta.prev` で次のページや前のページのリクエスト用 URL が提供されるため、
+そちらを利用したほうが良い場合もある。
+""",
+    "openapi_examples": {
+        "default": {
+            "summary": "100 (デフォルト)",
+            "value": 100,
+        },
+        "limit_50": {
+            "summary": "50",
+            "value": 50,
+        },
+    },
+}
+
 v1_data_posts_search_text: FastAPIEndpointParamDocs = {
     "description": """
 指定した文字列を含む Post を検索して取得する。検索は Post の本文に対して**完全一致**で行われる。
@@ -185,6 +225,8 @@ class FastAPIEndpointDocs(Generic[_KEY]):
         "note_id": v1_data_posts_note_id,
         "created_at_from": v1_data_posts_created_at_from,
         "created_at_to": v1_data_posts_created_at_to,
+        "offset": v1_data_posts_offset,
+        "limit": v1_data_posts_limit,
         "search_text": v1_data_posts_search_text,
         "search_url": v1_data_posts_search_url,
         "media": v1_data_posts_media,
@@ -253,6 +295,46 @@ class FastAPIEndpointDocs(Generic[_KEY]):
     },
 }
 
+v1_data_notes_offset: FastAPIEndpointParamDocs = {
+    "description": """
+取得するコミュニティノートのリストの先頭からのオフセット。ページネーションに利用される。
+
+
+ただし、レスポンスの `meta.next` や `meta.prev` で次のページや前のページのリクエスト用 URL が提供されるため、
+そちらを利用したほうが良い場合もある。
+""",
+    "openapi_examples": {
+        "default": {
+            "summary": "0 (デフォルト)",
+            "value": 0,
+        },
+        "offset_100": {
+            "summary": "100",
+            "value": 100,
+        },
+    },
+}
+
+v1_data_notes_limit: FastAPIEndpointParamDocs = {
+    "description": """
+取得するコミュニティノートのリストの最大数。 0 ～ 1000 まで指定できる。ページネーションに利用される。
+
+
+ただし、レスポンスの `meta.next` や `meta.prev` で次のページや前のページのリクエスト用 URL が提供されるため、
+そちらを利用したほうが良い場合もある。
+""",
+    "openapi_examples": {
+        "default": {
+            "summary": "100 (デフォルト)",
+            "value": 100,
+        },
+        "limit_50": {
+            "summary": "50",
+            "value": 50,
+        },
+    },
+}
+
 v1_date_notes_topic_ids: FastAPIEndpointParamDocs = {
     "description": """
 取得するコミュニティノートが紐づいているトピックの ID。
@@ -364,6 +446,8 @@ class FastAPIEndpointDocs(Generic[_KEY]):
         "note_ids": v1_data_notes_note_ids,
         "created_at_from": v1_data_notes_created_at_from,
         "created_at_to": v1_data_notes_created_at_to,
+        "offset": v1_data_notes_offset,
+        "limit": v1_data_notes_limit,
         "topic_ids": v1_date_notes_topic_ids,
         "post_ids": v1_data_notes_post_ids,
         "current_status": v1_data_notes_current_status,

diff --git a/api/birdxplorer_api/routers/data.py b/api/birdxplorer_api/routers/data.py
@@ -148,8 +148,8 @@ def get_notes(
             default=None, **V1DataNotesDocs.params["created_at_from"]
         ),
         created_at_to: Union[None, TwitterTimestamp] = Query(default=None, **V1DataNotesDocs.params["created_at_to"]),
-        offset: int = Query(default=0, ge=0),
-        limit: int = Query(default=100, gt=0, le=1000),
+        offset: int = Query(default=0, ge=0, **V1DataNotesDocs.params["offset"]),
+        limit: int = Query(default=100, gt=0, le=1000, **V1DataNotesDocs.params["limit"]),
         topic_ids: Union[List[TopicId], None] = Query(default=None, **V1DataNotesDocs.params["topic_ids"]),
         post_ids: Union[List[PostId], None] = Query(default=None, **V1DataNotesDocs.params["post_ids"]),
         current_status: Union[None, List[str]] = Query(default=None, **V1DataNotesDocs.params["current_status"]),
@@ -206,8 +206,8 @@ def get_posts(
         created_at_to: Union[None, TwitterTimestamp, str] = Query(
             default=None, **V1DataPostsDocs.params["created_at_to"]
         ),
-        offset: int = Query(default=0, ge=0),
-        limit: int = Query(default=100, gt=0, le=1000),
+        offset: int = Query(default=0, ge=0, **V1DataPostsDocs.params["offset"]),
+        limit: int = Query(default=100, gt=0, le=1000, **V1DataPostsDocs.params["limit"]),
         search_text: Union[None, str] = Query(default=None, **V1DataPostsDocs.params["search_text"]),
         search_url: Union[None, HttpUrl] = Query(default=None, **V1DataPostsDocs.params["search_url"]),
         media: bool = Query(default=True, **V1DataPostsDocs.params["media"]),