Swagger UI 上のドキュメントを整備する

[sushichan044]

Outline

#122
Swagger UI / openapi.json で確認できる API 仕様をより分かりやすいものにする。

• クエリパラメータ

  • FastAPI の Path() や Query() に対して引数でドキュメントを渡すことで自動的に整備できる。

• レスポンス

  • Annotated と Field(description="", examples=[]) を使って Type Hint でドキュメントを付与
  • 2箇所に分けて書く
  • Model のフィールドごとの説明: common 側の Pydantic Model 内でフィールドごとに付与
    • examples は指定しない
  • Reponse Object の examples: api 側の Response Model に付与

詳細

Docs

• /posts
  • description
  • param
  • response
• /notes
  • description
  • param
  • response
• /topics
  • description
• /user-enrollments
  • description
  • param

ある程度 Docs 書けたら

• 各種ドキュメントの examples に指定した ID について、確実にデータが見つかるものに変更する

[sushichan044]

Note

PR description へ転記済

note: レスポンスへの documentation は二箇所に分ける

• フィールドごとの説明: common の Pydantic Model 内でフィールドごとに付与
  • examples は指定しない
• Reponse Object の Example: 自動的に lowerCamelCase になる api 側の都合を common に出したくないので api 側の Response Model に付与