How to describe parameter in API call


#1

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

Best
Josh


#2

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


#3

@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:
    pass

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.