FastAPI 學習之路（三十七）後設資料和文件 URL

北漂的雷子發表於2021-10-22
ASTAPI

   你可以在 FastAPI 應用中自定義幾個後設資料配置。

你可以設定：

  • Title：在 OpenAPI 和自動 API 文件使用者介面中作為 API 的標題/名稱使用。

  • Description：在 OpenAPI 和自動 API 文件使用者介面中用作 API 的描述。

  • Version：API 版本，例如 v2 或者 2.5.0。

    • 如果你之前的應用程式版本也使用 OpenAPI 會很有用。

我們看下如何使用的

description = """
使用者建立和items建立
## Items

你可以讀他們

## Users

你可以做下面的:

* **建立使用者** 
* **讀取使用者** .
"""

app = FastAPI(
    title="系統介面",
    description=description,
    version="0.0.1"
)

我們看下實現後的效果，

 

 

你也可以使用引數 openapi_tags，為用於分組路徑操作的不同標籤新增額外的後設資料。

它接受一個列表，這個列表包含每個標籤對應的一個字典。

每個字典可以包含：

  • name（必要）：一個 str，它與路徑操作和 APIRouter 中使用的 tags 引數有相同的標籤名。

  • description：一個用於簡短描述標籤的 str。它支援 Markdown 並且會在文件使用者介面中顯示。

  • externalDocs：一個描述外部文件的 dict：

    • description：用於簡短描述外部文件的 str。

    • url（必要）：外部文件的 URL str。

使用方式

from fastapi import FastAPI
from routers.user import usersRouter
from routers.items import itemsRouter

tags_metadata = [
    {
        "name": "系統介面",
        "description": """
使用者建立和items建立
"""},
    {
        "name": "items",
        "description": "管理items，你可以檢視文件",
        "externalDocs": {
            "description": "使用文件",
            "url": "http://localhost:8000/docs#/Itmes",
        },
    },
]

app = FastAPI(
    openapi_tags=tags_metadata
)
app.include_router(usersRouter, prefix="/user", tags=['users'])
app.include_router(itemsRouter, prefix="/items", tags=['Itmes'])

最後的效果

 

 

文件 URLs

你可以配置兩個文件使用者介面，包括：

  • Swagger UI：服務於 /docs。

    • 可以使用引數 docs_url 設定它的 URL。

    • 可以通過設定 docs_url=None 禁用它。

  • ReDoc：服務於 /redoc。

    • 可以使用引數 redoc_url 設定它的 URL。

    • 可以通過設定 redoc_url=None 禁用它。

我們一直沒有看過redoc，我們今天看下

 

 我們重新定義下對應的文件的地址

app = FastAPI(
    openapi_tags=tags_metadata,
    docs_url="/openapi",
    redoc_url="/apidoc"
)

我們啟動後看下。

 

 

必須要訪問新的地址

 

 

 當然我們也可以禁用，可以根據我們的需求來。

文章首發在公眾號，歡迎關注。

相關文章