OpenAPI documentation for parameters

[mdw00d]

How do I associate descriptive text with parameters? E.g., if I have

@docs()
@app.route("/greet/{name}/")
async def greet(name:str, greeting: str = "Hello"):
    """
    The greet method for greeting people by name

    The greet method greets people.  What did you think it did?
    """
    return text(f"{greeting}, {name}! It's {datetime.utcnow().isoformat()}")

how would I associate a description with name and greeting?

[RobertoPrevato]

Hi @mdw00d,
Thanks for opening this discussion. Descriptions for parameters are not supported, yet.
I've been focused on other features for the framework lately, and I honestly even forgot to add this to the list of TODOs.

I create immediately an issue for this. I will include this one for the next release 1.0.4. I release often thanks to the automated jobs in GitHub Workflows.

[RobertoPrevato]

Note for myself or potential contributors.

It should be possible to specify parameter description explicitly using the @docs decorator, and possibly also by parsing the docstring.

For example, to support the following formats:

def send_message(sender, recipient, message_body, priority=1):
   '''
   Send a message to a recipient

   :param str sender: The person sending the message
   :param str recipient: The recipient of the message
   :param str message_body: The body of the message
   :param priority: The priority of the message, can be a number 1-5
   :type priority: integer or None
   :return: the message id
   :rtype: int
   :raises ValueError: if the message_body exceeds 160 characters
   :raises TypeError: if the message_body is not a basestring
   '''

And the numpy convention

Parameters
----------
x : type
    Description of parameter `x`.
y
    Description of parameter `y` (with type not specified).

[RobertoPrevato]

This has been implemented at #125, with basic support for several syntax styles. See https://github.com/Neoteroi/BlackSheep/blob/main/tests/test_openapi_docstrings.py for examples; I'll write documentation soon.