flask-apispec==0.8.7 : how to use apispec doctrings to populate the swagger documentation info?

[sandrotosi]

Hello, i have a very simple endpoint like this:

app = Flask(__name__)
docs = flask_apispec.FlaskApiSpec(app)

@app.route('/')
def main():
    """top-level stuff
    ---
    get:
        summary: whatever
        description: double whatever
        parameters: None
        responses:
            200:
                description: all good here
    """
    return "all good here\n"

docs.register(howdy)

but the swagger is never generated from the docstring. i can at least produce the description via @flask_apispec.annotations.doc(description='top-level stuff') but i couldnt find a way to populate the other information in the swagger interface with this decorator.

how do i use the apispec docstring with flask_apispec?

i have apispec==3.3.0 installed in this venv, in case it matters

thanks!

[goytia54]

Hello @sandrotosi , May I suggest using the @use_kwargs decorator for requests coupled with marshmallow schemas Then I would use @marshall_with decorator coupled with marshmallow schemas as well. Something like below:

If you don't want to use schemas just pass in None to schema

@app.route('/')
@marshal_with(schema=None, code=200, description='all good here')
def main():
    """top-level stuff
    ---
    get:
        summary: whatever
        description: double whatever
        parameters: None
        responses:
            200:
                description: all good here
    """
    return "all good here\n"

[sandrotosi]

what if i dont have any marchmallow schema, nor i want to create one? like i feel i should be able to use the apispec docstring with a bare-bone API no?

[goytia54]

@sandrotosi, you can pass in None, I have updated my answer

[adelavega]

@sandrotosi super late response but I would say that if you are not using Marshmallow, you're not getting the most out of flask_apispec. IMO the main contribubtion of flask-apispec is that you can use these decorators to simultaneously validate your arguments / outputs while auto-documenting.

You might be better off just using Flask's built in MethodView for writing your Resources and the apispec package for writing your Swager docs. I