[FEATURE] parameter documentation

The problem

I cannot add descriptions of parameters in OpenAPI documentation. (the specification by OpenAPI)

E.g.,

@app.get('/')
def get(param1: str, param2: int):
    ... do something

Here, there is no way to put descriptions of what param1 and param2 do.

Possible solutions

I can’t think of a clean solution. FastAPI is tightly using Python type check system for the documentation, which is a good thing, so we cannot easily add information to each parameter. Here are some possible solutions.

1. Parse docstring and embed the corresponding contents to parameter description. For example

@app.get('/')
def get(param1: str, param2: int):
    """
    - **param1**: param1 is doing the job1.
    - **param2**: param2 is doing the job2.
    """
    ... do something

The descriptions could be added to the specification of the parameters.

1. Use macro in comments. For example,

@app.get('/')
def get(param1: str,  # %FASTAPI%param1 is doing the job1.
        param2: int,  # %FASTAPI%param2 is doing the job2.
       ):
    ... do something

1. Based on @phy25’s comments, obviously Field could be supported at path, query and form parameters.

Please do let me know if I missed an existing feature for this. I am trying to switch from Flask to FastAPI for my basic web framework in Python, and most of the things look great so far. Thanks for the great project!

[maresb]

Summary of the above discussion.

The solution to

AttributeError: 'FieldInfo' object has no attribute 'in_'

when you have a query parameter like

param1: float = Field(None, description='This is doing something.'),

is to do

from fastapi import Query

and then change the above line to

param1: float = Query(None, description='This is doing something.'),

Here is the relevant documentation.

[jbkoh]

Hi @phy25 When I use

param1: float = Field(None, description='This is doing something.'),

It produces an error as

AttributeError: 'FieldInfo' object has no attribute 'in_'

at

fastapi/dependencies/utils.py", line 401, in add_param_to_fields
    if field_info.in_ == params.ParamTypes.path:

Would it be a bug?