Flask extension does not support blueprints #11
Comments
|
After centralizing the specs into the app declaration I have to explicitly provide an app context. |
|
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. |
|
@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). |
|
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. |
|
Can you please clarify how |
|
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 |
|
Ah, I see; the benefit would be that plugins could implement a paths_helper that would abstract extracting paths. Thanks for the clarification. An |
|
Notice a blueprint can be registered with a custom So you may need to do:
|
|
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 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 Then I created a function that iter the rules on 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()), 200And that's it, all the paths in my blueprint documented. |
|
@tinproject Tried this out for myself almost worked perfectly, except for me the |
|
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 |
|
@tinproject I noticed that your swagger.json is for the specific blueprint. Do you have a swagger.json for each blueprint? |
|
@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 |
|
If I can add something, the idea of doing view introspection before application is created is not optimal. I CAN support multiple rules per view etc. |
|
I attempted ( #27 ) to solve this problem creating a blueprint which adds all views to the spec. The 'adding' part takes place when you register the blueprint: |
|
As long as you don't care about blueprint groupings, this code would iterate over all the routing rules and add paths accordingly, similar to what from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
from apispec_webframeworks.flask import FlaskPlugin
from flask import Flask
spec = APISpec(
title="API",
version="0.1.0",
openapi_version="3.1.0",
info={"description": "The API"},
plugins=[MarshmallowPlugin(), FlaskPlugin()],
)
def init_apispec(app: Flask) -> None:
with app.test_request_context():
for rule in app.url_map.iter_rules():
spec.path(view=app.view_functions[rule.endpoint])Don't forget to add an |
Wednesday Apr 27, 2016 at 17:42 GMT
Originally opened as marshmallow-code/apispec#68
I have organized my views with Flask blueprints, but am unable to document them in the view file, because it is not executed in the application context.
Is there a way to keep the spec declarations with the blueprint? (It seems like there might not be.)
Do you think it would be useful to add the ability to add all the views from a blueprint at once?
I noticed that the flask extension seems to acknowledge that a view could contain multiple paths, but assumes it only contains one. apispec/ext/flask.py#L46
Maybe something like
spec.add_paths()could be added to handle compound view objects?The text was updated successfully, but these errors were encountered: