FastAPI 学习之路（三十七）元数据和文档 URL

前言

我们之前分享分享使用FastAPI 学习之路（三十七）引入APIRouter，这次我们分享元数据和文档 URL。

正文

你可以在 FastAPI 应用中自定义几个元数据配置。

你可以设定：

Title：在 OpenAPI 和自动 API 文档用户界面中作为 API 的标题/名称使用。
Description：在 OpenAPI 和自动 API 文档用户界面中用作 API 的描述。
Version：API 版本，例如 v2 或者 2.5.0。
- 如果你之前的应用程序版本也使用 OpenAPI 会很有用。

我们看下如何使用的

代码语言：javascript复制

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。

使用方式

代码语言：javascript复制

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，我们今天看下

我们重新定义下对应的文档的地址

代码语言：javascript复制

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

我们启动后看下。

必须要访问新的地址

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

后记

发现问题，解决问题。遇到问题，慢慢解决问题即可。

欢迎关注雷子说测试开发，后续将会持续为大家分享更多的技术知识

api php openapi

0 人点赞