leiziv5

   你可以在 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"
)

我们启动后看下。

 

 

必须要访问新的地址

 

 

 当然我们也可以禁用,可以根据我们的需求来。

文章首发在公众号,欢迎关注。

相关文章: