docs: query param for /v1/data/notes

api/birdxplorer_api/routers/data.py

@@ -21,7 +21,7 @@
 )
 from birdxplorer_common.storage import Storage
 
-from .openapi_doc import V1DataPostsQueryDocs
+from .openapi_doc import V1DataNotesQueryDocs, V1DataPostsQueryDocs
 
 
 class TopicListResponse(BaseModel):
@@ -73,13 +73,13 @@ def get_topics() -> TopicListResponse:
 
     @router.get("/notes", response_model=NoteListResponse)
     def get_notes(
-        note_ids: Union[List[NoteId], None] = Query(default=None),
-        created_at_from: Union[None, TwitterTimestamp] = Query(default=None),
-        created_at_to: Union[None, TwitterTimestamp] = Query(default=None),
-        topic_ids: Union[List[TopicId], None] = Query(default=None),
-        post_ids: Union[List[PostId], None] = Query(default=None),
-        current_status: Union[None, List[str]] = Query(default=None),
-        language: Union[LanguageIdentifier, None] = Query(default=None),
+        note_ids: Union[List[NoteId], None] = Query(default=None, **V1DataNotesQueryDocs.note_ids),
+        created_at_from: Union[None, TwitterTimestamp] = Query(default=None, **V1DataNotesQueryDocs.created_at_from),
+        created_at_to: Union[None, TwitterTimestamp] = Query(default=None, **V1DataNotesQueryDocs.created_at_to),
+        topic_ids: Union[List[TopicId], None] = Query(default=None, **V1DataNotesQueryDocs.topic_ids),
+        post_ids: Union[List[PostId], None] = Query(default=None, **V1DataNotesQueryDocs.post_ids),
+        current_status: Union[None, List[str]] = Query(default=None, **V1DataNotesQueryDocs.current_status),
+        language: Union[LanguageIdentifier, None] = Query(default=None, **V1DataNotesQueryDocs.language),
     ) -> NoteListResponse:
         return NoteListResponse(
             data=list(

api/birdxplorer_api/routers/openapi_doc.py

@@ -4,6 +4,8 @@
 from fastapi.openapi.models import Example
 from typing_extensions import TypedDict
 
+from birdxplorer_common.models import LanguageIdentifier
+
 
 class FastAPIQueryDocsRequired(TypedDict):
     description: str
@@ -166,3 +168,170 @@ class V1DataPostsQueryDocs:
     search_text = v1_data_posts_search_text
     search_url = v1_data_posts_search_url
     media = v1_data_posts_media
+
+
+v1_data_notes_note_ids: FastAPIQueryDocs = {
+    "description": """
+データを取得する X のコミュニティノートの ID。
+
+複数回クエリパラメータを指定する / カンマ区切りで複数の ID を指定することで複数のコミュニティノートを一括で取得できる。
+""",
+    "openapi_examples": {
+        "single": {
+            "summary": "コミュニティノートを 1つ取得する",
+            "value": ["1"],
+        },
+        "multiple_query": {
+            "summary": "コミュニティノートを複数取得する (クエリパラメータ)",
+            "value": ["1", "2"],
+        },
+        "multiple_comma": {
+            "summary": "コミュニティノートを複数取得する (カンマ区切り)",
+            "value": ["1,2"],
+        },
+    },
+}
+
+v1_data_notes_created_at_from: FastAPIQueryDocs = {
+    "description": """
+取得するコミュニティノートの作成日時の下限。**指定した日時と同時かそれより新しい**コミュニティノートのみを取得する。
+
+指定する形式は UNIX EPOCH TIME (ミリ秒) 。
+""",
+    "openapi_examples": {
+        "default": {
+            "summary": "指定しない (デフォルト)",
+            "value": None,
+        },
+        "normal": {
+            "summary": "2024 / 1 / 1 00:00 (JST) 以降のコミュニティノートを取得する",
+            "value": 1704034800000,
+        },
+    },
+}
+
+v1_data_notes_created_at_to: FastAPIQueryDocs = {
+    "description": """
+取得するコミュニティノートの作成日時の上限。**指定した日時よりも古い**コミュニティノートのみを取得する。
+
+指定する形式は UNIX EPOCH TIME (ミリ秒) 。
+""",
+    "openapi_examples": {
+        "default": {
+            "summary": "指定しない (デフォルト)",
+            "value": None,
+        },
+        "normal": {
+            "summary": "2024 / 7 / 1 00:00 (JST) より前のコミュニティノートを取得する",
+            "value": 1719759600000,
+        },
+    },
+}
+
+v1_date_notes_topic_ids: FastAPIQueryDocs = {
+    "description": """
+取得するコミュニティノートが紐づいているトピックの ID。
+
+`GET /api/v1/data/topics` で取得できるトピックの ID を指定することで、そのトピックに紐づいたコミュニティノートを取得できる。
+""",
+    "openapi_examples": {
+        "single": {
+            "summary": "トピックに紐づいたコミュニティノートを取得する",
+            "value": [1],
+        },
+        "multiple_query": {
+            "summary": "複数のトピックに紐づいたコミュニティノートを取得する (クエリパラメータ)",
+            "value": [1, 2],
+        },
+        "multiple_comma": {
+            "summary": "複数のトピックに紐づいたコミュニティノートを取得する (カンマ区切り)",
+            "value": ["1,2"],
+        },
+    },
+}
+
+v1_data_notes_post_ids: FastAPIQueryDocs = {
+    "description": """
+コミュニティノートのデータ取得に利用する X の Post の ID。
+コミュニティノートと Post は 1 : 1 で紐づいている。
+
+複数回クエリパラメータを指定する / カンマ区切りで複数の ID を指定することで複数のコミュニティノートを一括で取得できる。
+""",
+    "openapi_examples": {
+        "single": {
+            "summary": "Post に紐づいたコミュニティノートを 1つ取得する",
+            "value": ["1"],
+        },
+        "multiple_query": {
+            "summary": "複数の Post について、それぞれに紐づいたコミュニティノートを取得する (クエリパラメータ)",
+            "value": ["1", "2"],
+        },
+        "multiple_comma": {
+            "summary": "複数の Post について、それぞれに紐づいたコミュニティノートを取得する (カンマ区切り)",
+            "value": ["1,2"],
+        },
+    },
+}
+
+v1_data_notes_current_status: FastAPIQueryDocs = {
+    "description": """
+取得するコミュニティノートのステータス。
+
+| X 上の表示                                         | current_statusに指定する値  |
+| :------------------------------------------------: | :-------------------------: |
+| さらに評価が必要                                   | NEEDS_MORE_RATINGS          |
+| 現在のところ「役に立った」と評価されています       | CURRENTLY_RATED_HELPFUL     |
+| 現在のところ「役に立たなかった」と評価されています | CURRENTLY_RATED_NOT_HELPFUL |
+""",
+    "openapi_examples": {
+        "default": {
+            "summary": "指定しない (デフォルト)",
+            "value": None,
+        },
+        "needs_more_ratings": {
+            "summary": "さらに評価が必要なコミュニティノートを取得する",
+            "value": ["NEEDS_MORE_RATINGS"],
+        },
+        "currently_rated_helpful_or_currently_rated_not_helpful": {
+            "summary": "評価済みのコミュニティノートを取得する",
+            "value": ["CURRENTLY_RATED_HELPFUL", "CURRENTLY_RATED_NOT_HELPFUL"],
+        },
+    },
+}
+
+v1_data_notes_language: FastAPIQueryDocs = {
+    "description": """
+取得するコミュニティノートの言語。
+
+ISO 639-1 に準拠した 2 文字の言語コードを指定することで、その言語のコミュニティノートのみを取得できる。
+""",
+    "openapi_examples": {
+        "default": {
+            "summary": "指定しない (デフォルト)",
+            "value": None,
+        },
+        LanguageIdentifier.EN: {
+            "summary": "英語のコミュニティノートを取得する",
+            "value": LanguageIdentifier.EN,
+        },
+        LanguageIdentifier.JA: {
+            "summary": "日本語のコミュニティノートを取得する",
+            "value": LanguageIdentifier.JA,
+        },
+    },
+}
+
+
+@dataclass(frozen=True)
+class V1DataNotesQueryDocs:
+    """
+    `GET /api/v1/data/notes` のクエリパラメータの OpenAPI ドキュメント
+    """
+
+    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
+    topic_ids = v1_date_notes_topic_ids
+    post_ids = v1_data_notes_post_ids
+    current_status = v1_data_notes_current_status
+    language = v1_data_notes_language