FastAPI 访问不了API文档或配置不生效的解决方法

FastAPI中文教程

本文背景

FastAPI框架自带交互式api文档,通过路由/docs或者/redoc 访问，但是FastAPI 的文档界面（如 /docs 和 /redoc）依赖于外部的 JavaScript 和 CSS 库，如果项目部署环境网络不佳或者无法访问外网的时候，会因为无法获取外部库而无法正确访问交互式api文档界面，所以在实际项目中更推荐将外部文件下载到本地，然后修改文档引用的资源地址, 使用本地静态文件一方面能够提高请求性能（，因为它们在处理静态内容时通常效率更高），另一方面更加也安全。

下载必要的静态文件

Swagger UI 和 ReDoc 都有其前端静态资源，可以从它们的 GitHub repositories 中下载。

Swagger UI

1. 访问 Swagger UI GitHub Releases页面。
2. 下载 ZIP 文件（通常是最新的 release）并解压缩。
3. 从解压后的文件中找到 dist 文件夹复制到 FastAPI 项目的某个目录下，例如 static/swagger-ui

ReDoc

1. 访问 redoc.standalone.js 页面，将其另存为redoc.standalone.js并保存到FastAPI 项目的某个目录下，例如static/redoc
   

项目代码改造

1. 禁用 Swagger UI 和 ReDoc 文档

初始化FastAPI app时，禁用默认的api文档，app = FastAPI(docs_url=None, redoc_url=None) 注意，这里必须要禁用，否则访问/docs或者/redoc 查看api文档时还是访问的外网获取依赖文件，并没有使用项目中的静态文件

2. 挂载静态文件路径

app.mount("/static", StaticFiles(directory='static'), name="static")

3. 重写 /docs与/redoc路由

在上文中，在初始化应用时已经禁用了默认的接口文档路由，为了项目能够访问接口文档地址，我们需要重写接口路由，并且指定配置为本地的静态文件而不是在线的UI资源

@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
    return get_swagger_ui_html(
        openapi_url=app.openapi_url,
        title=app.title + " - Swagger UI",
        oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
        swagger_js_url="/static/swagger-ui/swagger-ui-bundle.js",
        swagger_css_url="/static/swagger-ui/swagger-ui.css",
        swagger_favicon_url="/static/swagger-ui/favicon-32x32.png",
    )

@app.get("/redoc", include_in_schema=False)
async def redoc_html():
    return get_redoc_html(
        openapi_url=app.openapi_url,
        title=app.title + " - ReDoc",
        redoc_js_url="/static/redoc/redoc.standalone.js",
        # redoc_favicon_url="/static/redoc/favicon.png" # 影响不大
    )

经过上述改造后，重启服务访问接口文档地址就可以发现，UI依赖文件已经不在访问外网获取而是使用项目的静态文件，完整代码查看后文

完整代码

# -*- coding: utf-8 -*-
import uvicorn
from typing import Union
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles
from fastapi.openapi.docs import get_swagger_ui_html, get_redoc_html

from pydantic import BaseModel

app = FastAPI(docs_url=None, redoc_url=None)

app.mount("/static", StaticFiles(directory='static'), name="static")


class Item(BaseModel):
    name: str
    price: float
    is_offer: Union[bool, None] = None


@app.get("/")
async def read_root():
    return {"Hello": "World"}


@app.get("/items/{item_id}")
async def read_item(item_id: int, q: Union[str, None] = None):
    return {"item_id": item_id, "q": q}


@app.put("/items/{item_id}")
def update_item(item_id: int, item: Item):
    return {"item_name": item.name, "item_id": item_id}


@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
    return get_swagger_ui_html(
        openapi_url=app.openapi_url,
        title=app.title + " - Swagger UI",
        oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
        swagger_js_url="/static/swagger-ui/swagger-ui-bundle.js",
        swagger_css_url="/static/swagger-ui/swagger-ui.css",
        swagger_favicon_url="/static/swagger-ui/favicon-32x32.png",
    )


@app.get("/redoc", include_in_schema=False)
async def redoc_html():
    return get_redoc_html(
        openapi_url=app.openapi_url,
        title=app.title + " - ReDoc",
        redoc_js_url="/static/redoc/redoc.standalone.js",
        # redoc_favicon_url="/static/redoc/favicon.png" # 可以不设置
    )


if __name__ == "__main__":
    uvicorn.run('main:app', host="127.0.0.1", port=8000, reload=True, workers=1)