FastAPI教程 元數(shù)據(jù)和文檔 URL

你可以在 FastAPI 應(yīng)用中自定義幾個元數(shù)據(jù)配置。

標(biāo)題、描述和版本

你可以設(shè)定：

• Title：在 OpenAPI 和自動 API 文檔用戶界面中作為 API 的標(biāo)題/名稱使用。
• Description：在 OpenAPI 和自動 API 文檔用戶界面中用作 API 的描述。
• Version：API 版本，例如 v2 或者 2.5.0。如果你之前的應(yīng)用程序版本也使用 OpenAPI 會很有用。

使用 title、description 和 version 來設(shè)置它們：

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

通過這樣設(shè)置，自動 API 文檔看起來會像：

標(biāo)簽元數(shù)據(jù)

你也可以使用參數(shù) openapi_tags，為用于分組路徑操作的不同標(biāo)簽添加額外的元數(shù)據(jù)。

它接受一個列表，這個列表包含每個標(biāo)簽對應(yīng)的一個字典。

每個字典可以包含：

• name（必要）：一個 str，它與路徑操作和 APIRouter 中使用的 tags 參數(shù)有相同的標(biāo)簽名。
• description：一個用于簡短描述標(biāo)簽的 str。它支持 Markdown 并且會在文檔用戶界面中顯示。
• externalDocs：一個描述外部文檔的 dict：description：用于簡短描述外部文檔的 str。url（必要）：外部文檔的 URL str。

創(chuàng)建標(biāo)簽元數(shù)據(jù)

讓我們在帶有標(biāo)簽的示例中為 users 和 items 試一下。

創(chuàng)建標(biāo)簽元數(shù)據(jù)并把它傳遞給 openapi_tags 參數(shù)：

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

注意你可以在描述內(nèi)使用 Markdown，例如「login」會顯示為粗體（login）以及「fancy」會顯示為斜體（fancy）。

提示

不必為你使用的所有標(biāo)簽都添加元數(shù)據(jù)。

使用你的標(biāo)簽

將 tags 參數(shù)和路徑操作（以及 APIRouter）一起使用，將其分配給不同的標(biāo)簽：

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

信息

閱讀更多關(guān)于標(biāo)簽的信息路徑操作配置。

查看文檔

如果你現(xiàn)在查看文檔，它們會顯示所有附加的元數(shù)據(jù)：

標(biāo)簽順序

每個標(biāo)簽元數(shù)據(jù)字典的順序也定義了在文檔用戶界面顯示的順序。

例如按照字母順序，即使 users 排在 items 之后，它也會顯示在前面，因為我們將它的元數(shù)據(jù)添加為列表內(nèi)的第一個字典。

OpenAPI URL

默認(rèn)情況下，OpenAPI 模式服務(wù)于 /openapi.json。

但是你可以通過參數(shù) openapi_url 對其進(jìn)行配置。

例如，將其設(shè)置為服務(wù)于 /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 模式，可以將其設(shè)置為 openapi_url=None，這樣也會禁用使用它的文檔用戶界面。

文檔 URLs

你可以配置兩個文檔用戶界面，包括：

• Swagger UI：服務(wù)于 /docs?？梢允褂脜?shù) docs_url 設(shè)置它的 URL?？梢酝ㄟ^設(shè)置 docs_url=None 禁用它。
• ReDoc：服務(wù)于 /redoc?？梢允褂脜?shù) redoc_url 設(shè)置它的 URL?？梢酝ㄟ^設(shè)置 redoc_url=None 禁用它。

例如，設(shè)置 Swagger UI 服務(wù)于 /documentation 并禁用 ReDoc：

from fastapi import FastAPI

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


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