How to doc a path with only optional queries?

[yurzo]

Path without parameters, only queries

declaring an str parameter, allows to capture queries as well as defining said parameter as optional.

@app.get("/items")
async def read_item(q: str = None):
...

however q is a clumsy string

alternatively:

from starlette.requests import Request
@app.get("/items")
async def read_item(request: Request):
...
    request.query_params #  <-- Neat dict with the query key/val pairs
...

However openapi does not have a way to say "optional query".
And /docs will not offer to execute a get with "optional query"

Is there a way to force or hard code the docs?
If you guys point me in the right direction, I could push the code.

While I did read though, I'm not sure I know where to start.

[tiangolo]

Hmm, I'm not sure what you want to achieve, I'm probably not understanding your use case.

It might be that you're thinking that q is the only valid query parameter? If that's the case, nope, you declare any parameter you need with the name you need, and it is documented as such.

See the examples for skip and limit.

[yurzo]

HI @tiangolo: Thanks for your quick response and fantastic work on fastapi BTW!

Consider these examples:

@router.get("/test_a")
async def ta(attribute_a: str = None):
    """
    """
    return {"attribute_a": attribute_a}

• attribute_a is optional in the docs
• http://0.0.0.0:5434/test_a?attribute_a=2 --> {"attribute_a":"2"}
• http://0.0.0.0:5434/test_a?attribute_a=2&attribute_b=3 --> {"attribute_a":"2"}

@router.get("/test_b")
async def tb(request: Request, attribute_a: str = None):
    """
    """
    return request.query_params

• attribute_a is optional in the docs
• attribute_b is not mentioned in the docs
• http://0.0.0.0:5434/test_b?attribute_a=2 --> {"attribute_a":"2"}
• http://0.0.0.0:5434/test_b?attribute_a=2&attribute_b=3 --> {"attribute_a":"2","attribute_b":"3"}

@router.get("/test_c")
async def tc(request: Request):
    """
    """
    return request.query_params

• None of the attributes is declared in the docs (of course)
• http://0.0.0.0:5434/test_b?attribute_a=2 --> {"attribute_a":"2"}
• http://0.0.0.0:5434/test_b?attribute_a=2&attribute_b=3 --> {"attribute_a":"2","attribute_b":"3"}

@router.get("/test_d")
async def tc(request: Request):
    """
    This function does something very interesting with the query
    """
    return request.query_params

• Desired outcome:

1. Document the fact that the endpoint accepts queries
2. Not explicitly declare all the query keys (query params change over time)
3. Enable the "try it out" with parameters for undeclared parameters

Is there a way this would be possible?
Where should I be looking in order to tweak this behavior in?
Thanks in advance!!!

[tiangolo]

HI @tiangolo: Thanks for your quick response and fantastic work on fastapi BTW!

I'm glad you're liking it!

Is there a way this would be possible?

Not really, that is not supported by OpenAPI, so, wouldn't show up in Swagger UI.

One alternative would be to have some predefined query parameters, and have their name dynamically created, using Query(None, alias=some_variable_with_the_query_param_name). But having an arbitrary amount of query parameters that are not defined in the OpenAPI is not supported by OpenAPI.

Still, you could do it, as you found out, but it wouldn't be "documentable".

[yurzo]

I get it now! Thanks!

[tiangolo]

Thanks for reporting back and closing the issue @yurzo ! 🚀