元数据和文档 URL¶
你可以在 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 服务条款的 URL。如果提供，则必须是 URL。 | ||||||||||||
contact | dict | 公开的 API 的联系信息。它可以包含多个字段。
|
| 参数 | 类型 | 描述 |
|---|---|---|
name | str | 联系人/组织的识别名称。 |
url | str | 指向联系信息的 URL。必须采用 URL 格式。 |
email | str | 联系人/组织的电子邮件地址。必须采用电子邮件地址的格式。 |
license_infodictlicense_info 字段
| 参数 | 类型 | 描述 |
|---|---|---|
name | str | 必须（如果设置了license_info）。用于 API 的许可证名称。 |
identifier | str | API 的SPDX 许可证表达式。字段identifier 与字段url 互斥。自 OpenAPI 3.1.0、FastAPI 0.99.0 起可用。 |
url | str | 用于 API 的许可证的 URL。必须采用 URL 格式。 |
你可以按如下方式设置它们：
fromfastapiimportFastAPIdescription="""ChimichangApp API helps you do awesome stuff. 🚀## ItemsYou can **read items**.## UsersYou 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/")asyncdefread_items():return[{"name":"Katana"}]提示
你可以在description 字段中编写 Markdown，它会在输出中渲染。
通过这样设置，自动 API 文档看起来会像：
许可证标识符¶
自 OpenAPI 3.1.0 和 FastAPI 0.99.0 起，你还可以在license_info 中使用identifier 而不是url。
例如：
fromfastapiimportFastAPIdescription="""ChimichangApp API helps you do awesome stuff. 🚀## ItemsYou can **read items**.## UsersYou 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":"Apache-2.0",},)@app.get("/items/")asyncdefread_items():return[{"name":"Katana"}]标签元数据¶
你也可以通过参数openapi_tags 为用于分组路径操作的不同标签添加额外的元数据。
它接收一个列表，列表中每个标签对应一个字典。
每个字典可以包含：
name（必填）：一个str，与在你的路径操作和APIRouter的tags参数中使用的标签名相同。description：一个str，该标签的简短描述。可以使用 Markdown，并会显示在文档 UI 中。externalDocs：一个dict，描述外部文档，包含：description：一个str，该外部文档的简短描述。url（必填）：一个str，该外部文档的 URL。
创建标签元数据¶
让我们在带有标签的示例中为users 和items 试一下。
创建标签元数据并把它传递给openapi_tags 参数：
fromfastapiimportFastAPItags_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"])asyncdefget_users():return[{"name":"Harry"},{"name":"Ron"}]@app.get("/items/",tags=["items"])asyncdefget_items():return[{"name":"wand"},{"name":"flying broom"}]注意你可以在描述内使用 Markdown，例如「login」会显示为粗体（login）以及「fancy」会显示为斜体（fancy）。
提示
不必为你使用的所有标签都添加元数据。
使用你的标签¶
将tags 参数和路径操作（以及APIRouter）一起使用，将其分配给不同的标签：
fromfastapiimportFastAPItags_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"])asyncdefget_users():return[{"name":"Harry"},{"name":"Ron"}]@app.get("/items/",tags=["items"])asyncdefget_items():return[{"name":"wand"},{"name":"flying broom"}]信息
阅读更多关于标签的信息路径操作配置。
查看文档¶
如果你现在查看文档，它们会显示所有附加的元数据：
标签顺序¶
每个标签元数据字典的顺序也定义了在文档用户界面显示的顺序。
例如按照字母顺序，即使users 排在items 之后，它也会显示在前面，因为我们将它的元数据添加为列表内的第一个字典。
OpenAPI URL¶
默认情况下，OpenAPI 模式服务于/openapi.json。
但是你可以通过参数openapi_url 对其进行配置。
例如，将其设置为服务于/api/v1/openapi.json：
fromfastapiimportFastAPIapp=FastAPI(openapi_url="/api/v1/openapi.json")@app.get("/items/")asyncdefread_items():return[{"name":"Foo"}]如果你想完全禁用 OpenAPI 模式，可以将其设置为openapi_url=None，这样也会禁用使用它的文档用户界面。
文档 URLs¶
你可以配置两个文档用户界面，包括：
- Swagger UI：服务于
/docs。- 可以使用参数
docs_url设置它的 URL。 - 可以通过设置
docs_url=None禁用它。
- 可以使用参数
- ReDoc：服务于
/redoc。- 可以使用参数
redoc_url设置它的 URL。 - 可以通过设置
redoc_url=None禁用它。
- 可以使用参数
例如，设置 Swagger UI 服务于/documentation 并禁用 ReDoc：
fromfastapiimportFastAPIapp=FastAPI(docs_url="/documentation",redoc_url=None)@app.get("/items/")asyncdefread_items():return[{"name":"Foo"}]