how to properly document python flask route

Question

i was trying to document this function and was wondering what kind of things I should include in the docstring. I am using sphinx as a documentation generator.

@app.route('/login', methods=['GET','POST'])
def login():
    """ 
    This is the Login route endpoint.

    Parameters:
        GET:/login

        POST:/login

    Returns:
        It renders the home.html template

    """
    form = LoginForm()

    if form.validate_on_submit():
        user = User.query.filter_by(username=form.username.data).first()
        if user:
            if check_password_hash(user.password_hash, form.password.data):
                login_user(user, remember=form.remember.data)
                return redirect('/dashboard')

        return '<h1> Invalid Username or Password!. Please try again.</h1>'


    return render_template('login.html', form = form)

Answer 1

I would suggest you use apispec, it has support for the OpenAPI Specification. There is also a Flask plugin and generates YAML for you.