Swaggerでエンドポイントを分類したい！

概要

FasAPIにはSwaggerUIという便利な機能が付いており、エンドポイントを簡単に叩くことができるため、開発にと手も便利です。
ですが、エンドポイントが増えてくると目的のエンドポイントが見つからなかったり、カテゴリごとに表示して可読性を高くしたいなんてことがあると思います。

今回は、Swaggerでエンドポイントを分類して表示する方法について記載していきます。

BeforeとAfter

• Before
  作成したエンドポイントが並んでいるが、ぱっと見でどれがどんな機能を持っているのかがわかりにくい。
  

• After
  各エンドポイントにタグをつけることで、分類して表示することができる。また、各エンドポイントの説明もあるため、どのような動きをするのかがわかりやすい。
  

設定方法

設定方法は単純で各エンドポイントにtags、summaryを設定するだけでOKです。

@router.get("/hello", tags=["ハロー"], summary="ハローを表示する", description="ここにエンドポイントの説明を記載する")

tagsはエンドポイントにつける「タグ」の名称を指定します。ここで指定したタグがグループ化されて表示されます。
summaryはエンドポイントの詳細を簡潔に記載します。似たようなものでdescriptionがありますが、こちらはより詳細にエンドポイントのについての説明事項を入力することでエンドポイントのリストビューで確認することができます。

まとめ

swaggerUIは非常に便利で特に設定をしなくてもエンドポイントのドキュメントとして役に立つので、タグ付けやエンドポイントの詳細を記載しておくことでチーム開発時に新規メンバーがキャッチアップする時にも非常に強力なドキュメントとなるので、手間を惜しまずに記載しておくと良さそうですね。