From 1ee791c82d7743cfc9b27b72c0102040ce4b2630 Mon Sep 17 00:00:00 2001 From: sushichan044 Date: Fri, 25 Oct 2024 19:55:42 +0900 Subject: [PATCH] docs: query param for /v1/data/notes --- api/birdxplorer_api/routers/data.py | 16 +- api/birdxplorer_api/routers/openapi_doc.py | 169 +++++++++++++++++++++ 2 files changed, 177 insertions(+), 8 deletions(-) diff --git a/api/birdxplorer_api/routers/data.py b/api/birdxplorer_api/routers/data.py index 98e8420..f86aff4 100644 --- a/api/birdxplorer_api/routers/data.py +++ b/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( diff --git a/api/birdxplorer_api/routers/openapi_doc.py b/api/birdxplorer_api/routers/openapi_doc.py index fb35f66..26d0eba 100644 --- a/api/birdxplorer_api/routers/openapi_doc.py +++ b/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