Inconsistency in openapi.json Generation for Annotated[list[str] | None] in FastAPI

[pygaiwan]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the FastAPI documentation, with the integrated search.
• I already searched in Google "How to X in FastAPI" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to FastAPI but to Pydantic.
• I already checked if it is not related to FastAPI but to Swagger UI.
• I already checked if it is not related to FastAPI but to ReDoc.

Commit to Help

• I commit to help with one of those options 👆

Example Code

# Failing

from typing import Annotated
from fastapi import FastAPI, Query


app = FastAPI()

@app.get('/items')
async def read_items(q: Annotated[list[str] | None, Query()] = None):
    query_items = {"q": q}
    return query_items

# Working
from typing import Annotated
from fastapi import FastAPI, Query


app = FastAPI()

@app.get('/items')
async def read_items(q: Annotated[list[str], Query()] = None):
    query_items = {"q": q}
    return query_items

Description

I've encountered an issue with FastAPI's Swagger UI not displaying the "Add item" button for a list[str] query parameter, conversely to what is described in FastAPI documentation. The problem arises when I define the function with the following signature:

async def read_items(q: Annotated[list[str] | None, Query()] = None):

In this case, the Swagger UI does not show the expected "Add item" button for the parameter q. However, when I modify the function definition by removing | None, the Swagger UI behaves as expected and the "Add item" button appears.

To understand the underlying issue, I compared the generated openapi.json files for both cases. The difference is highlighted below:

--- /tmp/with_none.json	2023-11-15 21:44:21
+++ /tmp/without_none.json	2023-11-15 21:44:34
@@ -15,10 +15,17 @@
             "in": "query",
             "required": false,
             "schema": {
-              "type": "array",
-              "items": {
-                "type": "string"
-              },
+              "anyOf": [
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                {
+                  "type": "null"
+                }
+              ],
               "title": "Q"
             }
           }

In the version with | None, the schema includes an anyOf with both an array type and a null type. This seems to be causing the Swagger UI to not render the "Add item" button correctly.

Operating System

Linux

Operating System Details

Debian GNU/Linux 12 (bookworm)

FastAPI Version

0.104.1

Pydantic Version

2.4.2

Python Version

Python 3.12.0

Additional Context

No response

[lmanc]

I have noticed the same thing.

[peterDitrih]

@tiangolo 🙏🙏

[Rich5]

+1 I also just ran into this bug

[JavierSanchezCastro]

From here #10836 (reply in thread)

Use:

from typing import Annotated
from fastapi import FastAPI, Query
from pydantic.json_schema import SkipJsonSchema

app = FastAPI()

@app.get('/items')
async def read_items(q: Annotated[list[str] | SkipJsonSchema[None], Query()] = None):
    query_items = {"q": q}
    return query_items

[Rich5]

Confirming that this fixes the issue for me. Thanks @JavierSanchezCastro!

[pygaiwan]

@JavierSanchezCastro thank you for your reply. Am I wrong or what you suggested is a workaround rather than a solution? It seems unusual to have to use a Pydantic class to have to deal with the OpenAPI schema. If that is the "approved" solution should that be documented somewhere?

[JavierSanchezCastro]

Yes! As you can see in #10836 coming from #10781 (comment), you can check that the following code is working on /redoc, showing that 'q' could be an array or a null value:

from typing import Annotated
from fastapi import FastAPI, Query

app = FastAPI()

@app.get('/items')
async def read_items(q: Annotated[list[str] | None, Query()] = None):
    query_items = {"q": q}
    return query_items

But the same code for /docs will not display the button as it interprets the openapi generated schema differently. In any case, I agree that this could be documented

[pygaiwan]

@Kludex just tagging you cause you marked the previous comment as the answer, do I need to raise an issue?

Or is that the actual real solution? If yes, can the docs be updated?
Thanks