fastapi/docs/ja/docs/tutorial/metadata.md

メタデータとドキュメントのURL

FastAPI アプリケーションのいくつかのメタデータ設定をカスタマイズできます。

APIのメタデータ

OpenAPI仕様および自動APIドキュメントUIで使用される次のフィールドを設定できます:

パラメータ	型	説明
title	str	APIのタイトルです。
summary	str	APIの短い要約です。 OpenAPI 3.1.0、FastAPI 0.99.0 以降で利用できます。
description	str	APIの短い説明です。Markdownを使用できます。
version	string	APIのバージョンです。これはOpenAPIのバージョンではなく、あなた自身のアプリケーションのバージョンです。たとえば 2.5.0 です。
terms_of_service	str	APIの利用規約へのURLです。指定する場合、URLである必要があります。
contact	dict	公開されるAPIの連絡先情報です。複数のフィールドを含められます。 contact fields Parameter Type Description name str 連絡先の個人/組織を識別する名前です。 url str 連絡先情報を指すURLです。URL形式である必要があります。 email str 連絡先の個人/組織のメールアドレスです。メールアドレス形式である必要があります。
license_info	dict	公開されるAPIのライセンス情報です。複数のフィールドを含められます。 license_info fields Parameter Type Description name str 必須（license_info が設定されている場合）。APIに使用されるライセンス名です。 identifier str APIの SPDX ライセンス式です。identifier フィールドは url フィールドと同時に指定できません。 OpenAPI 3.1.0、FastAPI 0.99.0 以降で利用できます。 url str APIに使用されるライセンスへのURLです。URL形式である必要があります。

以下のように設定できます:

{* ../../docs_src/metadata/tutorial001_py39.py hl[3:16, 19:32] *}

/// tip | 豆知識

description フィールドにはMarkdownを書けて、出力ではレンダリングされます。

///

この設定では、自動APIドキュメントは以下のようになります:

ライセンス識別子

OpenAPI 3.1.0 および FastAPI 0.99.0 以降では、license_info を url の代わりに identifier で設定することもできます。

例:

{* ../../docs_src/metadata/tutorial001_1_py39.py hl[31] *}

タグのメタデータ

パラメータ openapi_tags を使うと、パスオペレーションをグループ分けするために使用する各タグに追加のメタデータを追加できます。

それぞれのタグごとに1つの辞書を含むリストを取ります。

それぞれの辞書は以下を含められます:

• name (必須): パスオペレーション および APIRouter の tags パラメータで使用するのと同じタグ名の str。
• description: タグの短い説明の str。Markdownを含められ、ドキュメントUIに表示されます。
• externalDocs: 外部ドキュメントを説明する dict。以下を含みます:
  • description: 外部ドキュメントの短い説明の str。
  • url (必須): 外部ドキュメントのURLの str。

タグのメタデータの作成

users と items のタグを使った例で試してみましょう。

タグのメタデータを作成し、それを openapi_tags パラメータに渡します:

{* ../../docs_src/metadata/tutorial004_py39.py hl[3:16,18] *}

説明の中でMarkdownを使用できることに注意してください。たとえば「login」は太字 (login) で表示され、「fancy」は斜体 (fancy) で表示されます。

/// tip | 豆知識

使用するすべてのタグにメタデータを追加する必要はありません。

///

タグの使用

パスオペレーション（および APIRouter）の tags パラメータを使用して、それらを異なるタグに割り当てます:

{* ../../docs_src/metadata/tutorial004_py39.py hl[21,26] *}

/// info | 情報

タグの詳細は Path Operation Configuration{.internal-link target=_blank} を参照してください。

///

ドキュメントの確認

ここでドキュメントを確認すると、追加したメタデータがすべて表示されます:

タグの順番

タグのメタデータ辞書の順序は、ドキュメントUIに表示される順序の定義にもなります。

たとえば、users はアルファベット順では items の後に続きますが、リストの最初の辞書としてメタデータを追加したため、それより前に表示されます。

OpenAPI URL

デフォルトでは、OpenAPIスキーマは /openapi.json で提供されます。

ただし、パラメータ openapi_url を使用して設定を変更できます。

たとえば、/api/v1/openapi.json で提供されるように設定するには:

{* ../../docs_src/metadata/tutorial002_py39.py hl[3] *}

OpenAPIスキーマを完全に無効にする場合は、openapi_url=None を設定できます。これにより、それを使用するドキュメントUIも無効になります。

ドキュメントのURL

含まれている2つのドキュメントUIを設定できます:

• Swagger UI: /docs で提供されます。
  • URL はパラメータ docs_url で設定できます。
  • docs_url=None を設定することで無効にできます。
• ReDoc: /redoc で提供されます。
  • URL はパラメータ redoc_url で設定できます。
  • redoc_url=None を設定することで無効にできます。

たとえば、/documentation でSwagger UIが提供されるように設定し、ReDocを無効にするには:

{* ../../docs_src/metadata/tutorial003_py39.py hl[3] *}