flask-smorest
flask-smorest copied to clipboard
Schema description from docstring
I wondered why the models in the overview at the end of the Swagger UI didn't contain a model description and went down the rabbit hole to find that it seems to be an apispec issue.
It seems the apispec project doesn't see a need to provide an easy way to add descriptions to a marshmallow schema class since it's already possible to do
class ASchema(Schema):
a = fields.Int(description="description for a field")
spec.definition('ASchema', schema=ASchema, description="description for a definition, or a schema")
What would be a clean way to apply this to flask-smorest? Or am I doing it all wrong and there is a better way to have a components.schemas[].description added to in the resulting openapi.json?
I'd love if the class docstring could be used for this.
I think you're doing it right.
Grabbing a description from the docstring sounds like it could be a nice idea but honestly, I haven't had the time to give it much thought. Anyone interested in adding this feature via flask-smorest or apispec is welcome to investigate and share their findings here.