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

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

タイトル、説明文、バージョン¶

以下を設定できます:

タイトル: OpenAPIおよび自動APIドキュメントUIでAPIのタイトル/名前として使用される。
説明文: OpenAPIおよび自動APIドキュメントUIでのAPIの説明文。
バージョン: APIのバージョン。例: v2 または 2.5.0。 *たとえば、以前のバージョンのアプリケーションがあり、OpenAPIも使用している場合に便利です。

これらを設定するには、パラメータ title、description、version を使用します:

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://www.apache.org/licenses/LICENSE-2.0.html",
    },
)


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

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

タグのためのメタデータ¶

さらに、パラメータ openapi_tags を使うと、path operations をグループ分けするための複数のタグに関するメタデータを追加できます。

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

それぞれの辞書は以下をもつことができます:

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

タグのためのメタデータの作成¶

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

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

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.tiangolo.com/",
        },
    },
]

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"}]

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

豆知識

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

自作タグの使用¶

tags パラメーターを使用して、それぞれの path operations (および APIRouter) を異なるタグに割り当てます:

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.tiangolo.com/",
        },
    },
]

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"}]

情報

タグのより詳しい説明を知りたい場合は Path Operation Configuration を参照して下さい。

ドキュメントの確認¶

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

タグの順番¶

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

たとえば、users はアルファベット順では items の後に続きます。しかし、リストの最初に users のメタデータ辞書を追加したため、ドキュメントUIでは users が先に表示されます。

OpenAPI URL¶

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

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

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

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 を設定できます。これにより、それを使用するドキュメント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を無効にするには:

from fastapi import FastAPI

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


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