FastAPI 更换 docs文档风格

Lucas在澳洲

已于 2024-10-24 18:29:49 修改

阅读量727

点赞数 8

分类专栏： Python FastAPI 文章标签： fastapi 1024程序员节

于 2024-03-06 08:34:54 首次发布

本文链接：https://blog.csdn.net/weixin_50153843/article/details/136495330

版权

Python 同时被 2 个专栏收录

69 篇文章 6 订阅

订阅专栏

FastAPI

3 篇文章 0 订阅

订阅专栏

定制FastAPI生成的文档样式与布局

FastAPI 是一个基于 Python 的现代 Web 框架，它提供了自动生成 API 文档的功能，这些文档默认使用 Swagger UI 和 ReDoc 生成界面。虽然默认的文档界面已经足够满足大部分需求，但在某些情况下，我们可能希望对其样式或布局进行定制，以符合项目的品牌或提供更符合用户需求的界面。本篇文章将详细介绍如何定制 FastAPI 的 API 文档界面，包括修改默认的 Swagger UI 和 ReDoc 的样式与布局。

一、准备工作

在开始之前，确保您已经安装了 FastAPI 和 uvicorn，后者用于运行 FastAPI 应用。

在命令行中运行以下命令，安装 FastAPI 和必要的依赖：

pip install fastapi uvicorn

1-1 项目结构

在实现自定义文档页面之前，创建一个包含 templates 目录的基础项目结构，用于存放自定义的模板文件。假设我们正在构建一个名为 custom_fastapi_docs 的项目，项目结构如下所示：

custom_fastapi_docs/
│
├── main.py  # FastAPI 项目主文件
├── templates/
│    └── index.html  # 自定义Swagger UI模版
└── static/  # 静态文件目录（存放CSS、JavaScript等）

二、定制 Swagger UI 文档

FastAPI 默认使用 Swagger UI 来为开发者生成 API 文档界面。Swagger UI 是一个开源的工具，它能自动将 OpenAPI 规范展示为交互式的 API 文档界面。

2-1 创建 `templates/index.html` 自定义模板

首先，我们需要在 templates 目录下创建一个 index.html 文件。这个文件将作为自定义的文档主页，您可以在这里编写自定义的 HTML 和 CSS 代码来更换默认的样式和布局。

在 index.html 中，您可以保留基本的 Swagger UI 结构，但定制页面的外观和功能。假设我们想更改文档标题的样式，并添加一个自定义的导航栏，下面是一个基本的 index.html 示例：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Custom API Docs</title>
    <link rel="stylesheet" href="/static/styles.css"> <!-- 引入自定义CSS -->
</head>
<body>
    <!-- 自定义导航栏 -->
    <nav>
        <ul>
            <li><a href="/">Home</a></li>
            <li><a href="/custom-docs">API Documentation</a></li>
            <li><a href="/about">About Us</a></li>
        </ul>
    </nav>

    <!-- Swagger UI -->
    <div id="swagger-ui"></div>

    <!-- 引入Swagger相关的JS文件 -->
    <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@3.48.0/swagger-ui-bundle.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@3.48.0/swagger-ui-standalone-preset.js"></script>
    <script>
        const ui = SwaggerUIBundle({
            url: '/openapi.json',  <!-- FastAPI自动生成的API规范 -->
            dom_id: '#swagger-ui',
            presets: [
                SwaggerUIBundle.presets.apis,
                SwaggerUIStandalonePreset
            ],
            layout: 'StandaloneLayout'
        });
    </script>
</body>
</html>

在上面的示例中，我们引入了一个自定义的 CSS 文件（styles.css），并通过 Swagger UI 的 JavaScript 配置来加载我们的 API 规范文件 /openapi.json。此外，我们还添加了一个简单的导航栏，用于展示更多的页面链接。

2-2 创建 `static/styles.css` 自定义样式

在 static 目录下创建一个 styles.css 文件，用于定义页面的自定义样式。以下是一个简单的样式示例：

body {
    font-family: Arial, sans-serif;
}

nav ul {
    background-color: #333;
    overflow: hidden;
    color: white;
    padding: 0;
    margin: 0;
    list-style: none;
}

nav ul li {
    display: inline;
    padding: 20px;
}

nav ul li a {
    color: white;
    text-decoration: none;
    padding: 14px 20px;
    display: inline-block;
}

nav ul li a:hover {
    background-color: #111;
}

这段 CSS 修改了页面的字体，设置了导航栏的颜色和交互样式，使整个文档页面更具个性化。

2-3 修改 `main.py` 配置 FastAPI 静态文件与模板

接下来，我们需要修改 main.py 文件，将 FastAPI 生成的文档路径指向我们的自定义页面。首先引入 FastAPI 和 fastapi.staticfiles，并配置静态文件目录和自定义的文档路径。

from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles
from starlette.responses import HTMLResponse
from fastapi.templating import Jinja2Templates

app = FastAPI()

# 挂载静态文件路径
app.mount("/static", StaticFiles(directory="static"), name="static")

# 配置Jinja2模板引擎
templates = Jinja2Templates(directory="templates")

# 自定义的Swagger UI页面
@app.get("/custom-docs", response_class=HTMLResponse)
async def custom_swagger_ui():
    return templates.TemplateResponse("index.html", {"request": {}})

# 默认生成的API规范（可以保持不变）
@app.get("/openapi.json")
async def get_open_api_endpoint():
    return app.openapi()

2-4 启动 FastAPI 应用

保存所有更改后，运行以下命令启动 FastAPI 应用：

uvicorn main:app --reload

然后在浏览器中访问 http://localhost:8000/custom-docs，即可查看自定义样式和布局的 API 文档。

三、定制 ReDoc 文档

除了 Swagger UI，FastAPI 还默认生成了基于 ReDoc 的文档页面。与 Swagger UI 不同，ReDoc 侧重于以清晰的方式呈现 API 规范，因此很多项目喜欢使用 ReDoc 作为 API 文档的展示工具。我们也可以为 ReDoc 自定义样式和布局。

3-1 自定义 ReDoc 页面

与 Swagger UI 类似，我们可以创建自定义的 ReDoc 页面。首先，在 templates 目录下创建一个 redoc.html 文件：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Custom ReDoc API Docs</title>
    <link rel="stylesheet" href="/static/styles.css"> <!-- 引入自定义CSS -->
</head>
<body>
    <!-- 自定义导航栏 -->
    <nav>
        <ul>
            <li><a href="/">Home</a></li>
            <li><a href="/custom-redoc">ReDoc Documentation</a></li>
            <li><a href="/about">About Us</a></li>
        </ul>
    </nav>

    <!-- ReDoc渲染API规范 -->
    <redoc spec-url='/openapi.json'></redoc>

    <!-- 引入ReDoc的JS文件 -->
    <script src="https://cdn.jsdelivr.net/npm/redoc/bundles/redoc.standalone.js"></script>
</body>
</html>

在此模板中，我们通过 <redoc> 标签来加载 FastAPI 的 API 规范文件，并引入了 ReDoc 的 JavaScript 文件。这样，ReDoc 就会自动渲染我们的 API 规范。

3-2 修改 `main.py` 增加自定义 ReDoc 页面

接下来，回到 main.py，为 ReDoc 页面设置自定义路径：

@app.get("/custom-redoc", response_class=HTMLResponse)
async def custom_redoc():
    return templates.TemplateResponse("redoc.html", {"request": {}})

这样，您可以通过 http://localhost:8000/custom-redoc 来访问 ReDoc 风格的 API 文档。

四、总结

在本篇文章中，我们详细介绍了如何定制 FastAPI 生成的 API 文档样式与布局。通过创建自定义模板和修改 FastAPI 的默认文档配置，您可以轻松将 Swagger UI 和 ReDoc 的界面修改为符合项目需求的样式。此外，我们还探讨了如何引入自定义的静态文件（如 CSS），并配置 FastAPI 以便加载这些自定义资源。

定制化的 API 文档不仅能为开发者提供更好的使用体验，还能增强项目的品牌形象。如果您的项目对外提供 API 文档展示，这种定制化操作是非常有价值的。