FastAPI 交互式 API 文档

在进行 FastAPI 开发时，你可以享受到其他框架没有的一个好处：FastAPI 会自动为你生成 API 文档。这个文档还不止有一个，比如 Swagger UI 以及 ReDoc 。

Swagger UI 是一个流行的开源项目，它在大多数 API 文档业务中尤其受欢迎。它本身就支持自动生成 API 文档，并且你还可以很轻松地与它交互。

ReDoc 是另一个开源项目，它提供的是一个响应式的文档查看器。它可以帮助用户快速地浏览、测试和理解 API 路由的工作方式。

Swagger UI 模式下，通过访问 http://127.0.0.1:8000/docs即可看到这个文档。（需要使用代理，或者使用本站镜像）

ReDoc 模式下，通过访问 http://127.0.0.1:8000/docs即可看到这个文档。（和 Swagger UI 一样需要使用代理，也可以使用本站镜像）

通过交互式 API 文档可以看到， FastAPI 会自动列举 app 中定义的所有路由，包括这个路由所需传入的参数，以及这个参数对应的返回格式。你还可以很方便地对对应的接口进行请求。

API 文档的全局参数

FastAPI 提供的 Swagger UI 文档能设置很多东西，比如 API 的标题，版本以及版权信息等等，这些东西可以在创建 FastAPI 实例的时候传入，如下：

from fastapi import FastAPI

# 创建 FastAPI 实例
app = FastAPI(
    # API 文档的名字
    title="HeyPress",
    # API 文档的介绍
    description="HeyPress 的官方文档", 
    # API 的版本
    version="V1.0.0", 
    # 团队服务条款的 URL
    terms_of_service="https://www.yxqi.cn", 
    # 公开服务条款信息，包括名字，网站和邮箱
    contact={
        "name": "于小丘", 
        "url": "https://www.yxqi.cn", 
        "email": "admin@yuxiaoqiu.cn", 
    }, 
    # 项目的许可证，包括许可证名称和路径
    licence_info={
        "name": "GNU General Public License V3", 
        "url": "https://www.gnu.org/licenses/gpl-3.0.en.html", 
    }, 
    # API 接口分组
    openapi_tags={
        {
            "name": "接口分组1", 
            "decription": "接口分组1的信息说明", 
        },
        # 此处省略其他 API 接口分组
    },
    # 配置用于请求不同端点的host地址，可用于区分各种环境
    servers=[
        {"url": "/", "description": "本地开发环境"}, 
        {"url": "https://test.yxqi.cn", "description": "线上测试环境"}, 
        {"url": "https://www.yxqi.cn", "description": "生产环境"}, 
    ]
)

关闭 API 文档访问

FastAPI 提供的这俩 API 文档确实方便，但在生产环境开这玩意就不太礼貌了会有严重的安全隐患。你可以对其加上身份认证（后面的文档我会讲）或者IP白名单等等。如果你不需要 API 文档，也可以直接在 Nginx 里 Ban 掉他的访问节点，也可以直接用代码在创建 FastAPI 实例时 Ban 掉它的访问。如下：

from fastapi import FastAPI

app = FastAPI(
    # 关闭 Swagger UI
    docs_url=None, 
    # 关闭 ReDoc
    redoc_url=None, 
    # 或者也可以只把下面这个设置为None，这下进前两个会报错，因为Swagger UI和ReDoc依赖下面这个json文档
    openapi_url=None
)

单个 API 节点的参数（还在写）

# 省略部分代码

# 注意是写在装饰器里，而不是写在传入端点函数中
@app.get(
    path='/api/site/ping', 
    summary='测试站点连通性', 
    description='此API用于检查您的站点是否正常运行，以及您的应用程序是否能够正常连接到HeyPress。\n\n'
                '同时也将返回当前站点的域名/IP与客户端的IP地址。\n\n'
                '此API不需要任何参数，您可以直接访问此API来检查您的站点是否正常运行。'
)
def ping(request: Request):
    return {
        'code': 200, 
        'data': {
            'domain': request.base_url.hostname, 
            'client_ip': request.client.host
        },
        'msg': 'Pong'
        }