FastAPI swagger不喜欢通过查询参数传递的字符串列表，但endpoint可以在浏览器中工作

Question

FastAPI中的RESTAPIendpoint通过单个查询参数接受字符串列表，我遇到了一个问题。此endpoint的用法示例如下：

http://127.0.0.1:8000/items/2?short=false&response=this&response=that

在这里，名为“响应”的参数接受FastAPI教程中关于查询参数和字符串验证的部分中记录的字符串列表。endpoint在浏览器中按预期工作。

但是，它在Swagger文档中不起作用。单击“执行”以测试endpoint时，标记为“添加字符串项”的按钮会摇晃。Swagger UI似乎无法使用嵌入的查询参数创建预期的URL（如图1所示）。

endpoint的代码如下。我试过，有没有验证。

@app.get("/items/{item_ID}")
async def getQuestion_byID(item_ID: int = Path(
                    ...,
                    title = "Numeric ID of the question",
                    description = "Specify a number between 1 and 999",
                    ge = 1,
                    le = 999
                ), response: Optional[List[str]] = Query(
                    [],
                    title="Furnish an answer",
                    description="Answer can only have letters of the alphabet and is case-insensitive",
                    min_length=3,
                    max_length=99,
                    regex="^[a-zA-Z]+$"
                ), short: bool = Query(
                    False,
                    title="Set flag for short result",
                    description="Acceptable values are 1, True, true, on, yes"
                )):
    """
    Returns the quiz question or the result.
    Accepts item ID as path parameter and
    optionally response as query parameter.
    Returns result when the response is passed with the item ID. 
    Otherwise, returns the quiz question.
    """
    item = question_bank.get(item_ID, None)
    if not item:
        return {"question": None}
    if response:
        return evaluate_response(item_ID, response, short)
    else:
        return {"question": item["question"]}

感谢任何帮助。

Answer 1

如这里所述，这是由于OpenAPI将模式（以及最小和最大约束）应用于数组本身的架构，而不仅仅是数组中的单个项。如果您在http://127.0.0.1:8000/openapi.json检查OpenAPI架构，您会看到响应参数的架构如下所示（即，验证也应用于数组本身）：

      {
        "description": "Answer can only have letters of the alphabet and is case-insensitive",
        "required": false,
        "schema": {
          "title": "Furnish an answer",
          "maxLength": 99,
          "minLength": 3,
          "pattern": "^[a-zA-Z]+$",
          "type": "array",
          "items": {
            "maxLength": 99,
            "minLength": 3,
            "pattern": "^[a-zA-Z]+$",
            "type": "string"
          },
          "description": "Answer can only have letters of the alphabet and is case-insensitive",
          "default": []
        },
        "name": "response",
        "in": "query"
      }

正如这里提到的，您可以使用Pyd的配置来指定项目与该限制：

my_constr = constr(regex="^[a-zA-Z]+$", min_length=3, max_length=99)
response: Optional[List[my_constr]] = Query([], title="Furnish an...", description="Answer can...")

保持您的响应参数不变http://127.0.0.1:8000/openapi.json，从response（数组）模式中删除模式>（以及最小最大

    ...
    {
    "description": "Answer can only have letters of the alphabet and is case-insensitive",
    "required": false,
    "schema": {
      "title": "Furnish an answer",
      "type": "array",
      "items": {
        "maxLength": 99,
        "minLength": 3,
        "pattern": "^[a-zA-Z]+$",
        "type": "string"
      },
      "description": "Answer can only have letters of the alphabet and is case-insensitive",
      "default": []
    },
    "name": "response",
    "in": "query"
    },
    ...

然后，在应用程序中，指示FastAPI使用该模式：

import json
app.openapi_schema = json.load(open("my_openapi.json"))

由于上述解决方案要求您在每次进行更改或添加新endpoint/参数时复制和编辑架构，因此您宁愿按照此处所述修改OpenAPI架构。这将使您免于复制/编辑架构文件。请确保在代码末尾添加以下内容（在定义所有路由之后）。

from fastapi.openapi.utils import get_openapi

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="FastAPI",
        version="0.1.0",
        description="This is a very custom OpenAPI schema",
        routes=app.routes,
    )
    del openapi_schema["paths"]["/items/{item_ID}"]["get"]["parameters"][1]["schema"]["maxLength"]
    del openapi_schema["paths"]["/items/{item_ID}"]["get"]["parameters"][1]["schema"]["minLength"]
    del openapi_schema["paths"]["/items/{item_ID}"]["get"]["parameters"][1]["schema"]["pattern"]
    
    app.openapi_schema = openapi_schema
    return app.openapi_schema
    
    
app.openapi = custom_openapi

在上述所有解决方案中，通常显示在OpenAPI中< code>response下的约束注释(即< code >(query)maxlength:99 minlength:3 pattern:^[a-za-z]$ )不会出现(因为Swagger会从应用于< code>array而不是< code>items的约束中创建该注释)，但似乎没有办法保留这一点。然而，在解决方案2和3中，您可以修改上面的< code>JSON代码片段中所示的< code >“in”属性，以手动添加注释。但是，作为< code>HTML元素，等等。，由Swagger控制，整个注释将出现在括号内，约束之间没有换行符。尽管如此，您仍然可以通过在< code>Query参数的< code>description中指定应用于< code>items的约束来通知用户。