中繼資料和文件網址

您可以在 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 服務條款的網址。如果提供，則必須是網址。
contact	dict	公開 API 的聯絡資訊。它可以包含多個欄位。 contact 欄位 參數 類型 說明 name str 聯絡人/組織的識別名稱。 url str 指向聯絡資訊的網址。必須是網址格式。 email str 聯絡人/組織的電子郵件地址。必須是電子郵件地址格式。
license_info	dict	公開 API 的授權資訊。它可以包含多個欄位。 license_info 欄位 參數 類型 說明 name str 必要（如果設定了 license_info）。用於 API 的授權名稱。 identifier str API 的 SPDX 授權表達式。identifier 欄位與 url 欄位互斥。自 OpenAPI 3.1.0、FastAPI 0.99.0 起可用。 url str 用於 API 的授權網址。必須是網址格式。

您可以如下設定它們

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

提示

您可以在 description 欄位中撰寫 Markdown，它將在輸出中呈現。

使用此設定，自動 API 文件看起來會像

授權識別碼

自 OpenAPI 3.1.0 和 FastAPI 0.99.0 起，您也可以使用 identifier 而不是 url 來設定 license_info。

例如

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 為用於分組路徑操作的不同標籤新增其他中繼資料。

它需要一個包含每個標籤一個字典的清單。

每個字典可以包含

• name（必要）：一個 str，其標籤名稱與您在路徑操作和 APIRouter 中的 tags 參數中使用的相同。
• description：一個 str，包含標籤的簡短描述。它可以使用 Markdown，並會顯示在文件 UI 中。
• externalDocs：一個 dict，描述包含以下內容的外部文件
  • description：一個 str，包含外部文件的簡短描述。
  • 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.dev.org.tw/",
        },
    },
]

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*）。

提示

您不必為所有使用的標籤新增中繼資料。

使用您的標籤

使用 tags 參數搭配您的路徑操作（以及 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.dev.org.tw/",
        },
    },
]

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

資訊

在路徑操作設定中閱讀更多關於標籤的資訊。

查看文件

現在，如果您查看文件，它們將顯示所有額外的中繼資料

標籤順序

每個標籤中繼資料字典的順序也定義了在文件使用者介面中顯示的順序。

例如，即使 users 按字母順序應該排在 items 之後，它卻顯示在它們之前，因為我們將其元數據添加為列表中的第一個字典。

OpenAPI 網址

預設情況下，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，這也將停用使用它的文件使用者介面。

文件網址

您可以設定包含的兩個文件使用者介面

• Swagger UI：位於 /docs。
  • 您可以使用參數 docs_url 設定其網址。
  • 您可以透過設定 docs_url=None 將其停用。
• ReDoc：位於 /redoc。
  • 您可以使用參數 redoc_url 設定其網址。
  • 您可以透過設定 redoc_url=None 將其停用。

例如，要將 Swagger UI 設定為在 /documentation 提供服務並停用 ReDoc

from fastapi import FastAPI

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


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