Adding addtional documentation to `Query Parameters` for endpoints

[lewis-morris]

Is this possible at all?

I want to add a comment with explicit instructions for the query params, along with, possibly, extra information for each individual parameter.

Thoughts:

• overall comment could be added to the docstring of the schema.
• comments for each param could be added to the metadata attribute of each field.

OpenAPI 3 specs have:

• a description field for the Parameter Object which could house the comments for each parameter. It does, however, say it should be brief.
• each Operation Object has a "description" field which could hold the overall description of the params. Currently you are only populating the "summary" field. It the specs it says:

A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.

as i'm sure you know - I found this information all here.

[lewis-morris]

I've sifted through the code and found that you are already nearly doing this although its not in the repos docs.

A multi line docstring produces an "description" that can be markdown which will be very helpful.

Looking to see if I can work out why I can't make the description show on the query params.

[miguelgrinberg]

I think the documentation can benefit from having a detailed list of all the places in which documentation can be inserted. You would not only need to read the code of this package, but also of apispec which is the dependency that generates the OpenAPI code for Marshmallow schemas.

But in any case, as you already noticed, the docstrings from endpoints get their first line assigned to the operation summary, and the remaining lines to the description.

You can also add a description argument to any schema field, and apispec will copy that to the corresponding parameter object.

[lewis-morris]

I've just been through apispec's code, and found the part where they add the description, came here to mention it, but you've already beat me to it.

[miguelgrinberg]

This has been added in release 1.0 using annotations.