元数据和文档url

您可以在 FastAPI 应用程序中定制多个元数据配置。

标题、描述和版本

你可以设置:

• 标题: OpenAPI 文档中自定义文档标题
• 描述: OpenAPI 文档中自定义描述信息
• 版本: 2.5.0
  • 例如，一个应用程序有多个版本，也使用 OpenAPI，那么就很有用

要设置它们，使用参数标题、描述和版本:

from fastapi import FastAPI
app = FastAPI(
    title="My Super Project",
    description="This is a very fancy project, with auto docs for the API and everything",
    version="2.5.0",
)
@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]

使用这种配置，自动的 API 文档看起来像:

标签的元数据

您还可以为不同的标记添加额外的元数据，这些标记使用 openapi_tags 对路径操作进行分组
需要一个列表，每个标记包含一个字典
每本字典可以包含:

• name (required): 与您在路径操作和APIRouters中的tags参数中使用的标签名称相同
• description: 标签的简短描述。它可以是Markdown，并将显示在docs UI中
• externalDocs: 需要一个字典，描述外部的文档
  • description: 外部文档的简短描述
  • url ( ) : 外部文档的 URL

    为标记创建元数据

    让我们在一个有user和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"}]

注意，你可以在描述里面使用Markdown，比如 “login “会用粗体显示（login），”fancy “会用斜体显示（fancy）

:::info 小贴士
不必为使用的所有标签添加元数据 :::

使用标签

在路径操作中使用 tags参数，映射tags_metadata配置的标签

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

查看文档

如果检查文档，它们会显示所有额外的元数据:

标签顺序

每个标签元数据字典元素的顺序也定义了docs UI中显示的顺序。
例如，纵然users会按照字母顺序去追寻items，但却在他之前显示，因为我们将它们的元数据字典添加为列表中的第一个元素。

OpenAPI URL

默认配置文件/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，这也将禁用使用它的文档用户界面。

文档 url

可以配置以下两个文档用户界面:

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