Skip to content

Commit

Permalink
docs: エンドポイントごとにドキュメントをまとめられるようにする
Browse files Browse the repository at this point in the history
  • Loading branch information
@sushichan044
sushichan044 committed Oct 25, 2024
1 parent 760d3aa commit 41d8d13
Show file tree
Hide file tree
Showing 2 changed files with 61 additions and 47 deletions.
38 changes: 21 additions & 17 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 V1DataNotesQueryDocs, V1DataPostsQueryDocs
from .openapi_doc import V1DataNotesDocs, V1DataPostsDocs


class TopicListResponse(BaseModel):
Expand Down Expand Up @@ -71,15 +71,17 @@ def get_user_enrollment_by_participant_id(
def get_topics() -> TopicListResponse:
return TopicListResponse(data=list(storage.get_topics()))

@router.get("/notes", response_model=NoteListResponse)
@router.get("/notes", description=V1DataNotesDocs.description, response_model=NoteListResponse)
def get_notes(
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),
note_ids: Union[List[NoteId], None] = Query(default=None, **V1DataNotesDocs.query["note_ids"]),
created_at_from: Union[None, TwitterTimestamp] = Query(
default=None, **V1DataNotesDocs.query["created_at_from"]
),
created_at_to: Union[None, TwitterTimestamp] = Query(default=None, **V1DataNotesDocs.query["created_at_to"]),
topic_ids: Union[List[TopicId], None] = Query(default=None, **V1DataNotesDocs.query["topic_ids"]),
post_ids: Union[List[PostId], None] = Query(default=None, **V1DataNotesDocs.query["post_ids"]),
current_status: Union[None, List[str]] = Query(default=None, **V1DataNotesDocs.query["current_status"]),
language: Union[LanguageIdentifier, None] = Query(default=None, **V1DataNotesDocs.query["language"]),
) -> NoteListResponse:
return NoteListResponse(
data=list(
Expand All @@ -95,20 +97,22 @@ def get_notes(
)
)

@router.get("/posts", response_model=PostListResponse)
@router.get("/posts", description=V1DataPostsDocs.description, response_model=PostListResponse)
def get_posts(
request: Request,
post_id: Union[List[PostId], None] = Query(default=None, **V1DataPostsQueryDocs.post_id),
note_id: Union[List[NoteId], None] = Query(default=None, **V1DataPostsQueryDocs.note_id),
post_id: Union[List[PostId], None] = Query(default=None, **V1DataPostsDocs.query["post_id"]),
note_id: Union[List[NoteId], None] = Query(default=None, **V1DataPostsDocs.query["note_id"]),
created_at_from: Union[None, TwitterTimestamp, str] = Query(
default=None, **V1DataPostsQueryDocs.created_at_from
default=None, **V1DataPostsDocs.query["created_at_from"]
),
created_at_to: Union[None, TwitterTimestamp, str] = Query(
default=None, **V1DataPostsDocs.query["created_at_to"]
),
created_at_to: Union[None, TwitterTimestamp, str] = Query(default=None, **V1DataPostsQueryDocs.created_at_to),
offset: int = Query(default=0, ge=0),
limit: int = Query(default=100, gt=0, le=1000),
search_text: Union[None, str] = Query(default=None, **V1DataPostsQueryDocs.search_text),
search_url: Union[None, HttpUrl] = Query(default=None, **V1DataPostsQueryDocs.search_url),
media: bool = Query(default=True, **V1DataPostsQueryDocs.media),
search_text: Union[None, str] = Query(default=None, **V1DataPostsDocs.query["search_text"]),
search_url: Union[None, HttpUrl] = Query(default=None, **V1DataPostsDocs.query["search_url"]),
media: bool = Query(default=True, **V1DataPostsDocs.query["media"]),
) -> PostListResponse:
if created_at_from is not None and isinstance(created_at_from, str):
created_at_from = ensure_twitter_timestamp(created_at_from)
Expand Down
70 changes: 40 additions & 30 deletions api/birdxplorer_api/routers/openapi_doc.py
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
from dataclasses import dataclass
from typing import Dict
from typing import Dict, Generic

from fastapi.openapi.models import Example
from typing_extensions import TypedDict
from typing_extensions import LiteralString, TypedDict, TypeVar

from birdxplorer_common.models import LanguageIdentifier

Expand All @@ -15,6 +15,19 @@ class FastAPIEndpointQueryDocs(FastAPIEndpointQueryDocsRequired, total=False):
openapi_examples: Dict[str, Example]


_KEY = TypeVar("_KEY", bound=LiteralString)


@dataclass
class FastAPIEndpointDocs(Generic[_KEY]):
"""
FastAPI のエンドポイントのドキュメントをまとめた dataclass。
"""

description: str
query: Dict[_KEY, FastAPIEndpointQueryDocs]


v1_data_posts_post_id: FastAPIEndpointQueryDocs = {
"description": """
データを取得する X の Post の ID。
Expand Down Expand Up @@ -154,21 +167,18 @@ class FastAPIEndpointQueryDocs(FastAPIEndpointQueryDocsRequired, total=False):
},
}


@dataclass(frozen=True)
class V1DataPostsQueryDocs:
"""
`GET /api/v1/data/posts` のクエリパラメータの OpenAPI ドキュメント
"""

post_id = v1_data_posts_post_id
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
search_text = v1_data_posts_search_text
search_url = v1_data_posts_search_url
media = v1_data_posts_media

V1DataPostsDocs = FastAPIEndpointDocs(
"Post のデータを取得するエンドポイント",
{
"post_id": v1_data_posts_post_id,
"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,
"search_text": v1_data_posts_search_text,
"search_url": v1_data_posts_search_url,
"media": v1_data_posts_media,
},
)

v1_data_notes_note_ids: FastAPIEndpointQueryDocs = {
"description": """
Expand Down Expand Up @@ -324,16 +334,16 @@ class V1DataPostsQueryDocs:
}


@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
# GET /api/v1/data/notes のクエリパラメータの OpenAPI ドキュメント
V1DataNotesDocs = FastAPIEndpointDocs(
"コミュニティノートのデータを取得するエンドポイント",
{
"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 41d8d13

Please sign in to comment.