メタデータとドキュメントの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
を設定することで無効にできます。
- URL はパラメータ
- ReDoc:
/redoc
で提供されます。- URL はパラメータ
redoc_url
で設定できます。 redoc_url=None
を設定することで無効にできます。
- URL はパラメータ
たとえば、/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"}]