Fastapi: [FEATURE] parameter documentation

[jbkoh]

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!

[phy25]

https://fastapi.tiangolo.com/tutorial/body-fields/#declare-model-attributes

[jbkoh]

Thanks!

[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?

[jbkoh]

I am guessing the link works only for describing JSON body? I am reopening this issue.

[phy25]

Field works the same way as Query, Path and Body

So did you try the other classes?

[jbkoh]

@phy25 Ah got it. Thanks a lot! They work. I am closing this again :)

[tiangolo]

Thanks for the help here @phy25 ! :cake: :bowing_man:

Thanks @jbkoh for reporting back and closing the issue :+1:

[woostundy]

@phy25 Ah got it. Thanks a lot! They work. I am closing this again :)

How did you let it work?
when I use it for query param, got this error:

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

It works by 'fastAPI.Query' instead of 'Field'.

[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.