FastAPI Swagger界面操作级选项覆盖服务器选项问题咨询

问题说明 #

近期在FastAPI的Swagger界面出现弹窗，提示「部分操作级选项覆盖了全局服务器选项」，无法确定这是应用Bug还是正常情况，希望隐藏该提示信息。

相关代码 #

main.py #

from fastapi import FastAPI,Depends
from ml.model_recommendation import predict_intention
from ml.training_ml import create_ml
import crud,models,schemas
from db import SessionLocal,engine
from sqlalchemy.orm import Session
from typing import Optional
from enum import Enum
import numpy as np

app = FastAPI(title="ML prediction",description="API to serve data used for prediction of intended remediation date (IRD)")

class Tags(Enum):
    ITEMS = "Retrieve ITSO and Software Versions"
    DELETE = "Delete Data"
    INSERT = "Get IRD predictions"
    DOWNLOAD = "Download Data"


@app.on_event("startup")
def on_startup():
    models.Base.metadata.create_all(bind=engine)

# Dependency
def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()


@app.get(
    "/service_owners/",
    response_model=list[schemas.Evergreen],
    tags=[Tags.ITEMS]
)
def read_owners(service_owner: str ,software_product_version_name: Optional[str] = None,db: Session = Depends(get_db),skip: int = 0, limit: int = 100):
    owners = crud.get_service_owners(db,service_owner=service_owner,software_product_version_name=software_product_version_name,skip=skip,limit=limit)
    return owners

crud.py #

import models
from sqlalchemy.orm import Session
from sqlalchemy import select
from typing import Optional

def get_service_owners(db: Session, service_owner: str,software_product_version_name: Optional[str] = None,skip: int = 0, limit: int = 100):
    if software_product_version_name:
        stmt = (select(models.Evergreen.service_owner,models.Evergreen.software_product_version_name)
                .where(models.Evergreen.service_owner.ilike(f'%{service_owner}%'))
                .where(models.Evergreen.software_product_version_name.ilike(f'%{software_product_version_name}%'))
                ).distinct().offset(skip).limit(limit)
            
        return db.execute(stmt).all()
    
    stmt = select(models.Evergreen.service_owner,models.Evergreen.software_product_version_name).where(models.Evergreen.service_owner.ilike(f'%{service_owner}%')).distinct().offset(skip).limit(limit)
    return db.execute(stmt).all()

schemas.py #

from typing import Optional
from pydantic import BaseModel
from typing_extensions import TypedDict

class Evergreen(BaseModel):
    service_owner: Optional[str]
    software_product_version_name: Optional[str]

    class Config:
        from_attributes = True

class Items(TypedDict):
    service_owner: str 
    software_product_version_name: str 

class Pred(TypedDict):
    service_owner: str
    software_product_version_name: str 
    future_expectation: int 

原因与解决方案 #

原因分析 #

这个提示是正常现象，并非应用Bug。当接口的操作级配置（如请求参数规则、安全依赖等）与FastAPI全局服务器配置存在冲突或覆盖时，Swagger UI就会触发该提示。

隐藏提示的方法 #

方法1：通过Swagger UI配置禁用提示

初始化FastAPI时，添加swagger_ui_parameters参数，设置showCommonExtensions: False即可隐藏该提示：

app = FastAPI(
    title="ML prediction",
    description="API to serve data used for prediction of intended remediation date (IRD)",
    swagger_ui_parameters={"showCommonExtensions": False}
)

该参数会关闭Swagger UI的通用扩展提示，包括操作级覆盖全局的提示。

方法2：统一全局与操作级配置

如果希望从根源消除提示，可以排查所有接口的操作级配置，确保其与全局配置（如全局安全认证、响应模型规则等）保持一致，消除冲突后提示会自动消失。

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