FastAPI Swagger UI: Why Your Query Parameter Arrays Aren't Showing Up
If you're building an API with FastAPI and using Swagger UI for documentation, you might have run into this frustrating issue: your query parameters that are meant to be lists or arrays aren't showing up properly in the UI. Instead of seeing the expected input fields for each element in the array, you might see just one field with no clear way to input multiple values. This article will explain why this happens and offer a simple solution to fix it.
The Scenario:
Imagine you're building an API endpoint for searching products with multiple filters. You want to allow users to filter by multiple category values. Here's a typical FastAPI code snippet you might use:
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/products")
async def get_products(category: list[str] = Query(None, description="Category filters")):
# ... Your logic to fetch products based on categories
return {"products": [{"name": "Product A"}, {"name": "Product B"}]}
Now, when you access the Swagger UI at /docs, you'll likely find that the category parameter doesn't offer a clear way to input multiple categories.
The Issue:
The problem lies in how Swagger UI parses and displays query parameters. By default, it doesn't fully understand the intent of using a list type in your FastAPI route. It sees the category parameter as a single value, not a list of values.
The Solution:
The solution is to provide Swagger UI with explicit instructions on how to treat your array parameter. We can achieve this by using the Query parameter's alias and explode attributes.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/products")
async def get_products(category: list[str] = Query(None, description="Category filters", alias="category", explode=True)):
# ... Your logic to fetch products based on categories
return {"products": [{"name": "Product A"}, {"name": "Product B"}]}
Here's what we've done:
alias="category": This makes sure the parameter name in the UI matches the actual name in the FastAPI code.explode=True: This is the key! This tells Swagger UI to treat thecategoryparameter as a list of values, allowing users to input multiple categories by separating them with commas.
Now, when you refresh your Swagger UI, you'll see a clear input field where you can enter multiple values for the category parameter, separated by commas.
Additional Insights:
- This solution ensures that Swagger UI correctly renders your array parameters.
- The
explode=Trueattribute is particularly important for query parameters that are meant to be arrays. - You can use similar approaches to handle other collection types, like dictionaries.
Conclusion:
Understanding how Swagger UI interprets your API parameters is crucial for a seamless developer experience. By leveraging the alias and explode attributes, you can ensure that your array parameters are displayed correctly in your documentation, making your API more user-friendly and developer-friendly.
