Flask extension does not support blueprints about apispec

[deckar01]

A flask app with blueprints starts out looking something like:

from flask import Flask
from my_app.views.blueprint1 import blueprint1

app = Flask(__name__)

app.register_blueprint(blueprint1)

Blueprints are not defined in the flask application context, so the paths must be register to apispec in the flask app context:

from flask import Flask
from apispec import APISpec
from views.blueprint1 import blueprint1, view1, view2, view3, ...

spec = APISpec( ... )
app = Flask(__name__)

app.register_blueprint(blueprint1)

spec.add_path(view=view1)
spec.add_path(view=view2)
spec.add_path(view=view3)
...

This defeats the benefit of blueprints encapsulating view specific details away from the core application logic.

My current alternative is to import the app into a spec file and explicitly register the views within the app context. My core app logic is no longer aware of the blueprints implementation details, but I am still leaking those details outside of the blueprint.

Having the flask extension be able to register blueprints would correct the app blueprint encapsulation issue:

from flask import Flask
from apispec import APISpec
from views.blueprint1 import blueprint1

spec = APISpec( ... )
app = Flask(__name__)

app.register_blueprint(blueprint1)
spec.add_paths(views=blueprint1)

Having the flask extension add all the paths in an application at once would be icing on the cake.

from flask import Flask
from apispec import APISpec
from views.blueprint1 import blueprint1
from views.blueprint2 import blueprint2
from views.blueprint3 import blueprint3
...

spec = APISpec( ... )
app = Flask(__name__)

app.register_blueprint(blueprint1)
app.register_blueprint(blueprint2)
app.register_blueprint(blueprint3)
...

spec.add_paths(views=app)

This is really about providing a blessed pattern for large apps that have turned to blueprints for organization, then find the apispec docs no longer apply.

Maybe add_paths() is outside the scope of this project. An alternative is a wrapper library like apispec-flask-blueprints (following the example of marshmallow-jsonapi).

[jshwelz]

Hello, so what's the best approach for this issue? @sloria I would like to use blueprints.

[sloria]

Ah, I see; the benefit would be that plugins could implement a paths_helper that would abstract extracting paths. Thanks for the clarification.

An add_paths method is within scope of apispec. The question is whether is worth the increased API surface area. You presented a valid use case, and I would gladly review and merge a PR for it.

[lafrech]

@deckar01:

app.register_blueprint(blueprint1)
spec.add_paths(views=blueprint1)

Notice a blueprint can be registered with a custom url_prefix:

app.register_blueprint(simple_page, url_prefix='/pages')

So you may need to do:

app.register_blueprint(blueprint1, url_prefix='/pages')
spec.add_paths(views=blueprint1, url_prefix='/pages')

[tinproject]

I've come here because I try to add apispec to document an API that I have in a blueprint, I use flask view functions and not MethodViews, and ends up with a solution that believe interesting in this discussion.

As the url paths on flask are defined as Rules on Flask.url_map I define a helper based on path_from_view() that loads the path from a Rule object:

from apispec import Path, utils
from apispec.ext.flask import flaskpath2swagger

def path_from_rule(spec, rule, **kwargs):
    """Path helper that allows passing a Flask url Rule object."""
    path = flaskpath2swagger(rule.rule)
    view = current_app.view_functions.get(rule.endpoint)
    # Get operations from view function docstring
    operations = utils.load_operations_from_docstring(view.__doc__)
    return Path(path=path, operations=operations)

spec.register_path_helper(path_from_rule)

I ignored the current_app.config['APPLICATION_ROOT'] in path_from_view() as I couldn't find a standard explanation about it's use.

Then I created a function that iter the rules on url_map and add the path for the matching rules:

def add_paths_for_blueprint(spec, blueprint, exclude=()):
    bp_name = blueprint.name
    for r in current_app.url_map.iter_rules():
        ep = r.endpoint.split('.')
        if len(ep) == 1:  # App endpoint, not processed here
            break
        elif len(ep) == 2:  # Blueprint endpoint
            prefix, endpoint = ep[0], ep[1]
            if prefix == bp_name and endpoint not in exclude:
                spec.add_path(rule=r)
        else:
            raise ValueError("Not valid endpoint?", r.endpoint)

@bp.route('/swagger.json')
def get_swagger_json():
    spec = APISpec(...)  # Edited for clarity
    ...  # do other operation to spec, add definitions, etc.
    add_paths_for_blueprint(spec, bp, exclude=['get_swagger_json'])
    return jsonify(spec.to_dict()), 200

And that's it, all the paths in my blueprint documented.

[ccutch]

@tinproject Tried this out for myself almost worked perfectly, except for me the len(ep) == 1 condition should have resulted in a continue and not a break because there was an app route in between my blueprint routes. Not sure why that was the case but none the less thank you for this contribution!

[tinproject]

@andho If I remember well I had all my API inside a blueprint, sharing the Flask App with 'normal' web endpoints in other blueprints, but only one blueprint having the whole API.

Nothing avoids you to create the spec at the app level and use the add_paths_for_blueprint function to add the paths from different blueprints to the spec.

[deckar01]

After centralizing the specs into the app declaration I have to explicitly provide an app context.
http://stackoverflow.com/questions/31444036/runtimeerror-working-outside-of-application-context

[hello-josh]

@deckar01 I'd also wager that putting your spec.add_path setup in your blueprint directly could cause unexpected consequences if you ever decided to register a blueprint to your application multiple times.

[deckar01]

I ended up moving my spec declarations out of the execution path, so that the specs depend on the schema and views, but breaking changes to the specs do not affect the functionality of the app.

I break my specs up into files to mirror the schema/view structure and have a central spec instance that registers them within the flask app context. There is definitely some boiler plate that can be reduced, but it works.

It would be nice to be able to register a blueprint as a whole though. I'm not sure if it's possible, but it would be convenient if it was able to recognize the schema classes used by the blueprint and register those as well.

For now I will maintain a spec manifest that mirrors the API.

[deckar01]

@TRII @sloria How would you feel about exposing an interface for adding multiple paths at once?

I image the interface would look something like:

def add_paths(self, paths=None, **kwargs):
    """Add path objects to the spec.

    https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#pathsObject

    :param List[Path]|None path: List of Path instances
    :param dict kwargs: parameters used by any path helpers see :meth:`register_paths_helper`
    """

This would avoid a lot of boilerplate code if the paths are already available as a list.

This would allow the flask extension to support adding all the paths in a blueprint at once (or even all the paths in an app).

[sloria]

@deckar01 If we were to add add_paths, users might expect add_parameters, definitions, etc. to exist. What would add_paths provide that add_path within a for loop wouldn't provide?

[deckar01]

The ability for extensions to abstract registering collections of paths. I admit that a list of paths in userspace can easily be iterated, but navigating the internal structure of the path collections in a framework like flask is non-obvious.

In my use case 100% of my API needs to be documented. Every single view needing a duplicate spec declaration in a separate file creates a lot of opportunities for me or other developers to omit spec definitions. Allowing bulk registration reduces boilerplate and avoids pitfalls.

I understand the argument for maintaining a symmetrical interface. I don't have an argument for or against bulk parameter or definition registration, because I did not run into any issues with the standard registration pattern in my "growing" app.

Users who are scaling a flask app with blueprints are going to run into the same issue I did, because the only pattern suggested in the docs does not work with blueprints. The point of blueprints is to keep views organized in self contained collections, but now my views have to be explicitly imported in other files.

[sloria]

but now my views have to be explicitly imported in other files.

Can you please clarify how add_paths would address this problem?

[deckar01]

I am going to take a look at implementing this since @lafrech has provided another example of view collections in flask.

[tinproject]

I've been thinking about how can I solve this, a plugin helper that can add multiple paths at the same time is needed to properly document Flask apps.

In Flask a view function can have multiple url paths. A Rule in Flask has one url pattern associated with a flask endpoint, that is uniquely linked to a view function (or MethodView). Endpoints to view functions are one-to-one related, but url patterns to endpoints are many-to-one.

I'm currently implementing the add_paths function reference above but I'm not feel that is the better way, I'll open a new issue to discuss it.

[andho]

@tinproject I noticed that your swagger.json is for the specific blueprint. Do you have a swagger.json for each blueprint?

[lafrech]

Moved to https://github.com/marshmallow-code/apispec-webframeworks/.

[plourenco]

In case anyone is looking for an alternative, inspired by the comment above from @tinproject, I'm using the following:

def add_paths_for_blueprint(spec, blueprint, exclude=()):
  bp_name = blueprint.name
  for url_str, view in app.view_functions.items():
    url_paths = url_str.split('.')
    if len(url_paths) == 2:
      prefix, endpoint = url_paths
      if prefix == bp_name and endpoint not in exclude:
          spec.path(view=view)

with app.test_request_context():
  add_paths_for_blueprint(spec, bp, exclude=('index',))