5.0 KiB
Path Operationの設定
path operationデコレータを設定するためのパラメータがいくつかあります。
/// warning | 注意
これらのパラメータはpath operationデコレータに直接渡され、path operation関数に渡されないことに注意してください。
///
レスポンスステータスコード
path operationのレスポンスで使用する（HTTP）status_codeを定義することができます。
404のようにintのコードを直接渡すことができます。
しかし、それぞれの番号コードが何のためのものか覚えていない場合は、statusのショートカット定数を使用することができます:
{* ../../docs_src/path_operation_configuration/tutorial001_py310.py hl[1,15] *}
そのステータスコードはレスポンスで使用され、OpenAPIスキーマに追加されます。
/// note | 技術詳細
from starlette import statusを使用することもできます。
FastAPI は開発者の利便性を考慮して、fastapi.statusと同じstarlette.statusを提供しています。しかし、これはStarletteから直接提供されています。
///
タグ
tagsパラメータをstrのlist（通常は１つのstr）と一緒に渡すと、path operationにタグを追加できます:
{* ../../docs_src/path_operation_configuration/tutorial002_py310.py hl[15,20,25] *}
これらはOpenAPIスキーマに追加され、自動ドキュメントのインターフェースで使用されます:
Enumを使ったタグ
大きなアプリケーションの場合、複数のタグが蓄積されていき、関連するpath operationsに対して常に同じタグを使っていることを確認したくなるかもしれません。
このような場合、タグをEnumに格納すると理にかなっています。
FastAPI は、プレーンな文字列の場合と同じ方法でそれをサポートしています:
{* ../../docs_src/path_operation_configuration/tutorial002b_py39.py hl[1,8:10,13,18] *}
概要と説明
summaryとdescriptionを追加できます:
{* ../../docs_src/path_operation_configuration/tutorial003_py310.py hl[17:18] *}
docstringを用いた説明
説明文は長くて複数行におよぶ傾向があるので、関数docstring内にpath operationの説明文を宣言できます。すると、FastAPI は説明文を読み込んでくれます。
docstringにMarkdownを記述すれば、正しく解釈されて表示されます。（docstringのインデントを考慮して）
{* ../../docs_src/path_operation_configuration/tutorial004_py310.py hl[17:25] *}
これは対話的ドキュメントで使用されます:
レスポンスの説明
response_descriptionパラメータでレスポンスの説明をすることができます。
{* ../../docs_src/path_operation_configuration/tutorial005_py310.py hl[18] *}
/// info | 情報
response_descriptionは具体的にレスポンスを参照し、descriptionはpath operation全般を参照していることに注意してください。
///
/// check | 確認
OpenAPIはpath operationごとにレスポンスの説明を必要としています。
そのため、それを提供しない場合は、FastAPI が自動的に「成功のレスポンス」を生成します。
///
path operationを非推奨にする
path operationをdeprecatedとしてマークする必要があるが、それを削除しない場合は、deprecatedパラメータを渡します:
{* ../../docs_src/path_operation_configuration/tutorial006_py39.py hl[16] *}
対話的ドキュメントでは非推奨と明記されます:
path operationsが非推奨である場合とそうでない場合でどのように見えるかを確認してください:
まとめ
path operationデコレータにパラメータを渡すことで、path operationsのメタデータを簡単に設定・追加することができます。