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

• [x] /posts
  • [x] description
  • [x] param
  • [x] response
• [x] /notes
  • [x] description
  • [x] param
  • [x] response
• [x] /topics
  • [x] description
• [x] /user-enrollments
  • [x] description
  • [x] param

ある程度 Docs 書けたら

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

[sushichan044]

[!NOTE] PR description へ転記済

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

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