Is it possible to add descriptions to path and/or query parameters?

[GeoSander]

Hi,

First of all: thanks for creating and maintaining this project - I like it a lot more than the "regular" Django REST framework!

I was wondering if there is a way to add descriptions to path and query parameters, so that they show up in the Swagger UI?

I tried the FastAPI approach for this, since the same parameter functions seem to be available in Ninja too, for example:

@api.post("tasks/{serial}/{task_id}/map", summary="bla bla", tags=["tasks", "maps"])
def upload_map(request,
               serial: str = Path(..., description="The device serial number."),
               task_id: uuid.UUID = Path(..., description="The UUID of the task to which the map belongs."),
               overwrite: bool = Query(False, description="Overwrite an existing map.")):
    """ Uploads the map data for the given device and task."""
    return {
        "device": serial,
        "task": task_id,
        "overwrite": overwrite
    }

Django runs fine like this, but there are still no descriptions in the Swagger UI:

Is this even possible? Or do I need to edit the default Swagger HTML template for the descriptions to show up?

Thanks,
Sander

[vitalik]

Hi @GeoSander

this looks like a bug (#326)

[GeoSander]

Thanks for sorting that out @vitalik. I was too lazy 😉
Will you fix it or should I try and make a PR?

[vitalik]

@GeoSander fixed in 0.16.2

[GeoSander]

Great, thanks! 🙏

[jonesnc]

I have a question about this snippet:

Path(..., description="The device serial number.")

Could someone explain what ... does?

[vitalik]

@jonesnc
... is a special python constant Ellipsis

in case of Django ninja it is used to mark that this field is required (does not have default value)

[jonesnc]

Thanks!