search

marshmallow-code / flask-smorest

DB agnostic framework to build auto-documented REST APIs with Flask and marshmallow
https://flask-smorest.readthedocs.io
MIT License
639 stars 72 forks source link

Proposal: Allow register_blueprint option to name the Blueprint outside of Flask #567

Open spra85 opened 9 months ago

spra85 commented 9 months ago

Would like to have the option to use a different, more user-friendly name for OpenAPI/Swagger UI Blueprints without needing to change the underlying Flask Blueprint name.

Currently, register_blueprint looks for the name option to be passed in and falls back on Blueprint.name (see: https://github.com/marshmallow-code/flask-smorest/blob/master/flask_smorest/blueprint.py#L180).

Suggestion, something like the below to add a docs_name option to use a different name from the name option, which is also used by the FlaskBlueprint and materially changes the actual route reference that might be used by Flask url_for. 

blp_name = options.get("docs_name") or options.get("name", blueprint.name)

If this is an acceptable solution/idea, I can submit a PR. I could be misinterpreting the appropriate place for this change.

lafrech commented 3 months ago

What is wrong about setting that user-friendly string as blueprint name?

I think this is what is do (although I don't put long sentences in there, generally a single work like "User" for the blueprint with user management routes).

The change you propose sounds reasonable but before adding API surface, I'd like to understand current limitation.