如何用FastAPI内置功能在Swagger OpenAPI文档中添加图片与自定义字段

你提到的所有自定义需求都可以通过 FastAPI 内置的 OpenAPI 扩展能力实现，无需完全独立托管 OpenAPI JSON 文件，以下是具体实现方法：

1. 添加自定义字段（联系信息、作者、数据库字段等） #

全局自定义字段 #

实例化 FastAPI 时可通过 contact、openapi_extra 等参数添加全局自定义内容，会自动写入生成的 OpenAPI schema 中：

from fastapi import FastAPI

app = FastAPI(
    title="业务接口文档",
    # 全局联系信息
    contact={
        "name": "运维支持组",
        "email": "support@domain.com",
    },
    # 全局自定义字段入口
    openapi_extra={
        "department": "技术部",
        "update_cycle": "每周一迭代"
    }
)

单接口自定义字段 #

在路径操作装饰器的 openapi_extra 参数中添加对应接口的自定义属性，支持任意自定义字段：

# 给单个接口添加作者、关联数据库字段等信息
@app.get("/goods/list", openapi_extra={
    "author": "李小明",
    "contact": "lixiaoming@domain.com",
    "related_db_fields": ["goods_id", "goods_name", "price", "stock", "create_time"]
})
async def get_goods_list():
    return {"code": 0, "data": []}

2. 在文档中插入图片（数据模型图、库表结构等） #

Swagger UI 原生支持 Markdown 渲染，你可以在任意描述字段（接口描述、模型描述、自定义板块描述）中插入图片：

from pydantic import BaseModel

class GoodsModel(BaseModel):
    """
    商品数据模型
    结构示意图：
    ![商品模型结构](本地静态资源地址/内部图床地址)
    
    关联库表：`mall.goods`
    """
    goods_id: int
    goods_name: str
    price: float
    stock: int

如果需要在文档顶部/独立板块插入图片，可以通过重写 OpenAPI 生成逻辑在 schema 中添加自定义板块，板块描述中插入图片即可。

3. 自定义 HTML 版 Swagger 文档托管 #

你可以直接替换 FastAPI 默认的 /docs 路由，使用自定义的 Swagger UI 模板：

from fastapi.openapi.docs import get_swagger_ui_html
from fastapi.responses import HTMLResponse

# 覆盖默认的Swagger文档路由
@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui() -> HTMLResponse:
    return get_swagger_ui_html(
        openapi_url=app.openapi_url,
        title=app.title + " - 自定义接口文档",
        # 可替换为本地托管的Swagger静态资源地址
        swagger_js_url="/static/swagger-ui-bundle.js",
        swagger_css_url="/static/swagger-ui.css",
        # 支持注入自定义HTML、添加Swagger UI配置参数
    )

如果需要完全定制的文档样式，也可以自行编写HTML模板，只要在模板中正确加载项目的 /openapi.json 地址即可正常渲染接口文档。

完全自定义OpenAPI生成逻辑 #

如果默认生成的OpenAPI schema无法满足需求，可以重写app.openapi()方法，自行修改生成的schema内容：

from fastapi.openapi.utils import get_openapi

def custom_openapi():
    # 缓存生成的schema避免重复计算
    if app.openapi_schema:
        return app.openapi_schema
    # 生成默认的openapi schema
    openapi_schema = get_openapi(
        title=app.title,
        version=app.version,
        openapi_version=app.openapi_version,
        description=app.description,
        routes=app.routes,
    )
    # 任意修改schema内容，比如添加自定义顶级板块
    openapi_schema["x-custom-model-section"] = {
        "title": "全量数据模型说明",
        "description": "![全局数据模型图](静态资源地址) \n 所有模型对应数据库字段见下表..."
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema

# 替换默认的openapi生成方法
app.openapi = custom_openapi

内容的提问来源于stack exchange，提问作者searcot jabali