flask-smorest icon indicating copy to clipboard operation
flask-smorest copied to clipboard

Schema description from docstring

Open heeplr opened this issue 3 years ago • 1 comments

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.

heeplr avatar Aug 17 '21 11:08 heeplr

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.

lafrech avatar Aug 23 '21 13:08 lafrech