fastapi swagger 静态资源

FastAPI是一个轻量级的Web框架，它允许开发者快速构建RESTful APIs。Swagger是一个流行的文档生成工具，用于提供API的交互式文档。当你将Swagger集成到FastAPI项目中时，可以方便地创建和展示API的文档，包括静态资源。

静态资源是指那些不会随着HTTP请求动态变化的内容，比如HTML、CSS、JavaScript文件等。在FastAPI和Swagger结合时，你可以通过`@app.get("/openapi.json")`这样的装饰器，返回一个包含Swagger元数据的JSON文件，这个文件会被浏览器用来显示API文档。同时，对于静态资源，你需要设置一个目录路径，例如：

@app.get("/{filename:path}")
async def static_file(filename: str):
    return FileResponse(directory="/path/to/static/files/" + filename)

这里，`/path/to/static/files/`是你存储静态文件的实际路径。访问`http://yourdomain.com/path/to/static/files/yourfile.css`时，会直接返回静态文件，而不会触发FastAPI的业务逻辑。

相关问题

fastapi 生成api文档失败

### 解决FastAPI生成API文档失败的问题

当在局域网环境中使用 FastAPI 自动生成功能时，可能会因为无法访问 CDN 而导致 `docs` 接口文档不可用[^4]。为了克服这一挑战并确保 API 文档能够正常工作，可以采取以下措施：

#### 修改配置以本地托管静态文件

通过调整 FastAPI 的设置来实现静态资源的本地化部署是一个有效的解决方案。具体来说，在应用启动前定义好路径映射，使得 Swagger UI 或 ReDoc 所需的所有 CSS 和 JavaScript 文件都指向本地服务器而不是外部 CDN。

from fastapi import FastAPI
import uvicorn
from starlette.staticfiles import StaticFiles

app = FastAPI()

# 将 static 目录下的文件作为静态资源提供服务
app.mount("/static", StaticFiles(directory="static"), name="static")

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

if __name__ == "__main__":
    uvicorn.run(app, host='0.0.0.0', port=8000)

此代码片段展示了如何挂载一个名为 `/static` 的目录用于存储前端所需的静态资产，并将其集成到 FastAPI 应用程序中。

#### 使用自定义模板覆盖默认UI

如果仅修改静态文件位置还不够解决问题，则可以通过创建自定义 HTML 页面的方式完全替换掉原有的 Swagger UI 或者 ReDoc 界面。这允许更灵活地控制页面加载哪些脚本以及它们来自哪里。

对于这种方案，需要先下载完整的 Swagger UI 或 ReDoc 发布包至项目的某个子文件夹内（比如命名为 `swagger_ui`），接着按照官方指南编写相应的入口HTML文件，最后利用 FastAPI 提供的 `get_swagger_ui_html()` 方法指定新地址即可完成定制化操作[^2]。

from pathlib import Path
from fastapi.openapi.docs import get_swagger_ui_html
...

@app.get("/custom-docs")
async def custom_docs():
    return get_swagger_ui_html(
        openapi_url="/openapi.json",
        title="Custom Docs",
        swagger_js_url="/static/swagger-ui-bundle.js",  # 指向本地js
        swagger_css_url="/static/swagger-ui.css"       # 指向本地css
    )

上述例子说明了怎样构建一个新的端点 `/custom-docs` 来呈现经过特别设计后的 API 文档视图，其中所有的依赖项均来源于内部网络可触及之处。

---