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

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

APIのメタデータ¶

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

パラメータ型説明

タイトル 文字列 APIのタイトル。

概要 文字列 APIの簡単な概要。 OpenAPI 3.1.0、FastAPI 0.99.0以降で利用可能。

説明 文字列 APIの簡単な説明。Markdownを使用できます。

バージョン 文字列 APIのバージョン。これはOpenAPIのバージョンではなく、ご自身のアプリケーションのバージョンです。例えば2.5.0。

利用規約 文字列 APIの利用規約へのURL。提供された場合、これはURLでなければなりません。

連絡先

辞書

公開されているAPIの連絡先情報。いくつかのフィールドを含めることができます。

contact フィールド

パラメータ	型	説明
`名前`	`文字列`	連絡担当者/組織の識別名。
`URL`	`文字列`	連絡先情報へのURL。URL形式である必要があります。
`メール`	`文字列`	連絡担当者/組織のメールアドレス。メールアドレス形式である必要があります。

ライセンス情報

辞書

公開されているAPIのライセンス情報。いくつかのフィールドを含めることができます。

license_info フィールド

パラメータ	型	説明
`名前`	`文字列`	必須 (`license_info`が設定されている場合)。APIに使用されるライセンス名。
`識別子`	`文字列`	APIのSPDXライセンス表現。`identifier`フィールドは`url`フィールドと相互排他的です。 OpenAPI 3.1.0、FastAPI 0.99.0以降で利用可能。
`URL`	`文字列`	APIに使用されるライセンスへのURL。URL形式である必要があります。

次のように設定できます。

Python 3.8以上

from fastapi import FastAPI

description = """
ChimichangApp API helps you do awesome stuff. 🚀

## Items

You can **read items**.

## Users

You will be able to:

* **Create users** (_not implemented_).
* **Read users** (_not implemented_).
"""

app = FastAPI(
    title="ChimichangApp",
    description=description,
    summary="Deadpool's favorite app. Nuff said.",
    version="0.0.1",
    terms_of_service="http://example.com/terms/",
    contact={
        "name": "Deadpoolio the Amazing",
        "url": "http://x-force.example.com/contact/",
        "email": "dp@x-force.example.com",
    },
    license_info={
        "name": "Apache 2.0",
        "url": "https://apache.dokyumento.jp/licenses/LICENSE-2.0.html",
    },
)


@app.get("/items/")
async def read_items():
    return [{"name": "Katana"}]

ヒント

descriptionフィールドにMarkdownを記述すると、出力でレンダリングされます。

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

ライセンス識別子¶

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

例えば

Python 3.8以上

from fastapi import FastAPI

description = """
ChimichangApp API helps you do awesome stuff. 🚀

## Items

You can **read items**.

## Users

You will be able to:

* **Create users** (_not implemented_).
* **Read users** (_not implemented_).
"""

app = FastAPI(
    title="ChimichangApp",
    description=description,
    summary="Deadpool's favorite app. Nuff said.",
    version="0.0.1",
    terms_of_service="http://example.com/terms/",
    contact={
        "name": "Deadpoolio the Amazing",
        "url": "http://x-force.example.com/contact/",
        "email": "dp@x-force.example.com",
    },
    license_info={
        "name": "Apache 2.0",
        "identifier": "MIT",
    },
)


@app.get("/items/")
async def read_items():
    return [{"name": "Katana"}]

タグのメタデータ¶

openapi_tagsパラメータを使用して、パス操作をグループ化するために使用される異なるタグの追加メタデータを追加することもできます。

各タグの辞書を1つずつ含むリストを受け取ります。

各辞書には次のものを含めることができます。

name (必須): パス操作およびAPIRouterのtagsパラメータで使用するのと同じタグ名のstr。
description: タグの簡単な説明を含むstr。Markdownを含めることができ、ドキュメントUIに表示されます。
externalDocs: 外部ドキュメントを記述するdict
- description: 外部ドキュメントの簡単な説明を含むstr。
- url (必須): 外部ドキュメントのURLを含むstr。

タグのメタデータを作成する¶

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

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

Python 3.8以上

from fastapi import FastAPI

tags_metadata = [
    {
        "name": "users",
        "description": "Operations with users. The **login** logic is also here.",
    },
    {
        "name": "items",
        "description": "Manage items. So _fancy_ they have their own docs.",
        "externalDocs": {
            "description": "Items external docs",
            "url": "https://fastapi.dokyumento.jp/",
        },
    },
]

app = FastAPI(openapi_tags=tags_metadata)


@app.get("/users/", tags=["users"])
async def get_users():
    return [{"name": "Harry"}, {"name": "Ron"}]


@app.get("/items/", tags=["items"])
async def get_items():
    return [{"name": "wand"}, {"name": "flying broom"}]

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

ヒント

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

タグを使用する¶

パス操作（およびAPIRouter）でtagsパラメータを使用して、それらを異なるタグに割り当てます。

Python 3.8以上

from fastapi import FastAPI

tags_metadata = [
    {
        "name": "users",
        "description": "Operations with users. The **login** logic is also here.",
    },
    {
        "name": "items",
        "description": "Manage items. So _fancy_ they have their own docs.",
        "externalDocs": {
            "description": "Items external docs",
            "url": "https://fastapi.dokyumento.jp/",
        },
    },
]

app = FastAPI(openapi_tags=tags_metadata)


@app.get("/users/", tags=["users"])
async def get_users():
    return [{"name": "Harry"}, {"name": "Ron"}]


@app.get("/items/", tags=["items"])
async def get_items():
    return [{"name": "wand"}, {"name": "flying broom"}]

情報

タグの詳細については、パス操作の設定を参照してください。

ドキュメントを確認する¶

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

タグの順序¶

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

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

OpenAPIのURL¶

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

しかし、openapi_urlパラメータで設定できます。

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

Python 3.8以上

from fastapi import FastAPI

app = FastAPI(openapi_url="/api/v1/openapi.json")


@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]

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

ドキュメントのURL¶

含まれる2つのドキュメントユーザーインターフェースを設定できます。

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

例えば、Swagger UIを/documentationで提供し、ReDocを無効にするには

Python 3.8以上

from fastapi import FastAPI

app = FastAPI(docs_url="/documentation", redoc_url=None)


@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]