Skip to content

Commit

Permalink
docs: query param for /v1/data/notes
Browse files Browse the repository at this point in the history
  • Loading branch information
@sushichan044
sushichan044 committed Oct 25, 2024
1 parent c793b24 commit 1ee791c
Show file tree
Hide file tree
Showing 2 changed files with 177 additions and 8 deletions.
16 changes: 8 additions & 8 deletions api/birdxplorer_api/routers/data.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@
)
from birdxplorer_common.storage import Storage

from .openapi_doc import V1DataPostsQueryDocs
from .openapi_doc import V1DataNotesQueryDocs, V1DataPostsQueryDocs


class TopicListResponse(BaseModel):
Expand Down Expand Up @@ -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(
Expand Down
169 changes: 169 additions & 0 deletions api/birdxplorer_api/routers/openapi_doc.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

0 comments on commit 1ee791c

Please sign in to comment.