O parâmetro de consulta q é do tipo Union[str, None], o que significa que é do tipo str mas que também pode ser None, e de fato, o valor padrão é None, então o FastAPI saberá que não é obrigatório.
Observação
O FastAPI saberá que o valor de q não é obrigatório por causa do valor padrão = None.
O Union em Union[str, None] não é usado pelo FastAPI, mas permitirá que seu editor lhe dê um melhor suporte e detecte erros.
Note que substituímos o valor padrão de None para Query(default=None), o primeiro parâmetro de Query serve para o mesmo propósito: definir o valor padrão do parâmetro.
Então:
q:Union[str,None]=Query(default=None)
...Torna o parâmetro opcional, da mesma maneira que:
q:Union[str,None]=None
Mas o declara explicitamente como um parâmetro de consulta.
Informação
Tenha em mente que o FastAPI se preocupa com a parte:
=None
Ou com:
=Query(default=None)
E irá utilizar o None para detectar que o parâmetro de consulta não é obrigatório.
O Union é apenas para permitir que seu editor de texto lhe dê um melhor suporte.
Então, podemos passar mais parâmetros para Query. Neste caso, o parâmetro max_length que se aplica a textos:
q:str=Query(default=None,max_length=50)
Isso irá validar os dados, mostrar um erro claro quando os dados forem inválidos, e documentar o parâmetro na operação de rota do esquema OpenAPI..
Essa expressão regular específica verifica se o valor recebido no parâmetro:
^: Inicia com os seguintes caracteres, ou seja, não contém caracteres anteriores.
fixedquery: contém o valor exato fixedquery.
$: termina aqui, não contém nenhum caractere após fixedquery.
Se você se sente perdido com todo esse assunto de "expressão regular", não se preocupe. Esse é um assunto complicado para a maioria das pessoas. Você ainda pode fazer muitas coisas sem utilizar expressões regulares.
Mas assim que você precisar e já tiver aprendido sobre, saiba que você poderá usá-las diretamente no FastAPI.
Quando você não necessita de validações ou de metadados adicionais, podemos fazer com que o parâmetro de consulta q seja obrigatório por não declarar um valor padrão, dessa forma:
q:str
em vez desta:
q:Union[str,None]=None
Mas agora nós o estamos declarando como Query, conforme abaixo:
Dessa forma o FastAPI saberá que o parâmetro é obrigatório.
Lista de parâmetros de consulta / múltiplos valores¶
Quando você declara explicitamente um parâmetro com Query você pode declará-lo para receber uma lista de valores, ou podemos dizer, que irá receber mais de um valor.
Por exemplo, para declarar que o parâmetro q pode aparecer diversas vezes na URL, você escreveria:
você receberá os múltiplos parâmetros de consultaq com os valores (foo e bar) em uma lista (list) Python dentro da função de operação de rota, no parâmetro da funçãoq.
Assim, a resposta para essa URL seria:
{"q":["foo","bar"]}
Dica
Para declarar um parâmetro de consulta com o tipo list, como no exemplo acima, você precisa usar explicitamente o Query, caso contrário será interpretado como um corpo da requisição.
A documentação interativa da API irá atualizar de acordo, permitindo múltiplos valores:
Lista de parâmetros de consulta / múltiplos valores por padrão¶
E você também pode definir uma lista (list) de valores padrão caso nenhum seja informado:
Você pode adicionar mais informações sobre o parâmetro.
Essa informações serão inclusas no esquema do OpenAPI e utilizado pela documentação interativa e ferramentas externas.
Observação
Tenha em mente que cada ferramenta oferece diferentes níveis de suporte ao OpenAPI.
Algumas delas não exibem todas as informações extras que declaramos, ainda que na maioria dos casos, esses recursos estão planejados para desenvolvimento.
fromtypingimportUnionfromfastapiimportFastAPI,Queryapp=FastAPI()@app.get("/items/")asyncdefread_items(q:Union[str,None]=Query(default=None,title="Query string",description="Query string for the items to search in the database that have a good match",min_length=3,),):results={"items":[{"item_id":"Foo"},{"item_id":"Bar"}]}ifq:results.update({"q":q})returnresults
Agora vamos dizer que você não queria mais utilizar um parâmetro.
Você tem que deixá-lo ativo por um tempo, já que existem clientes o utilizando. Mas você quer que a documentação deixe claro que este parâmetro será descontinuado.
Então você passa o parâmetro deprecated=True para Query:
fromtypingimportUnionfromfastapiimportFastAPI,Queryapp=FastAPI()@app.get("/items/")asyncdefread_items(q:Union[str,None]=Query(default=None,alias="item-query",title="Query string",description="Query string for the items to search in the database that have a good match",min_length=3,max_length=50,pattern="^fixedquery$",deprecated=True,),):results={"items":[{"item_id":"Foo"},{"item_id":"Bar"}]}ifq:results.update({"q":q})returnresults