-
-
Notifications
You must be signed in to change notification settings - Fork 177
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Documenting callable default #196
Comments
Ah, that makes sense. Good catch. I think your proposed |
There is no way to document a dynamic default: OAI/OpenAPI-Specification#554. What we should do is allow the user to opt-out of default documenting. Then he can either specify the default behaviour in the description or add a So we need an attribute meaning "don't document default". From the discussion in OAI/OpenAPI-Specification#554, datetime is the only common use case. Not documenting callable defaults is not really an option, as we'll miss |
On second thought, since a callable could be anything, it could be smarter to not document them. There is no reason the value returned by the callable at documentation time makes sense in this context. An exception to this would be basic types that are provided as callables to avoid the "same list instance in every field instance" issue. Those are common enough to justify an exception to the rule. So if default is not marshmallow.missing:
if callable(default):
if default in (dict, list, set,...): # How to get an exhaustive list?
ret['default'] = default()
else:
# Don't assume anything and let the user add a note in the description
pass
else:
ret['default'] = default We could add a EMPTY_COLLECTION_CALLABLES = (dict, list, set,...) # How to get an exhaustive list?
if default_doc:
if callable(default_doc):
ret['default'] = default_doc()
else:
ret['default'] = default_doc
elif default is not marshmallow.missing:
if callable(default) and default in EMPTY_COLLECTION_CALLABLES:
ret['default'] = default()
else:
ret['default'] = default |
I'd like to tackle this. Using the callable's return value to fill the doc default is wrong, so removing this would be a bugfix. Besides, it is not tested, so no test broken. Edit: My bad, it is tested in I wanted to make an exception for However, it would be nice to have another meta attribue to allow passing a default manually. This one could also be used when |
When a default/missing value is a callable, it is called when generating the documentation.
This can be wrong if the value of the callable depends on the moment it is called. Typically, if it is
dt.datetime.now
. There should be an opt-out for this allowing to specify an alternative text to write in the docs.Not sure how to do that. Maybe a
default_doc
attribute in the Schema that would take precedence over default/missing.The text was updated successfully, but these errors were encountered: