How to describe parameter in API call


Hey there,

I am very excited to see that the automatic API documentation was reimplemented. Unfortunately I do struggle a bit when it comes to filling out the parameter description field. I figured out that the docstring will be automatically extracted but did not find any overview the documentation of the query parameter (see attached screenshot).



Also it would be nice if the doc-string of a component could be added to the endpoint’s description e.g.:

class Admin:
    """requires administrator privileges"""
    # ...

class AdminComponent(Component):
    def reslove(self, authorization: http.Header) -> Admin:
        # ...
        return Admin(...)

def my_end_point(admin: Admin):
     # ...

routes = [Route('/my/end/point', 'GET', my_end_point)]

Than /my/end/point/ should have the requires administrator privileges somewhere in its description


@jgoerner Those descriptions showed up for me once I wrote a types.Type-derived class, and provided the description params to validators instantiated for its attributes. The class is then used as type hint for the view handler parameter representing the query params:

class MyRequestParams(types.Type):
    content = validators.String(max_length=1024 * 1024 * 10, description='Text content to tag')
    offset = validators.Integer(minimum=0, allow_null=True, description='Paging offset')
    limit = validators.Integer(minimum=1, allow_null=True, description='Paging limit')

def my_handler(params: MyRequestParams) -> dict:

This works for request body validation, I haven’t found a way to do the same for URL query parameters / parameters dict you would annotate as http.QueryParam/http.QueryParams.