marshmallow-code / marshmallow-code/flask-smorest
renaming args in api spec
- Dominant language
- Python
- Stars
- 717
- Forks
- 77
- Avg merge
- 7h 49m
- Merged PRs (30d)
- 3
Description
This is either a feature request or a failure on my part to find documentation
I'm making use of converters reasonably heavily to create endpoints with my model already extracted from my database.
```python
class PetConverter(BaseConverter):
def __init__(self, url_map):
super().__init__(url_map)
self.regex = r'[0-9]+'
def to_python(self, value):
return Pet.query.filter_by(id=value).first_or_404()
def to_url(self, value):
return str(value.id)
app.url_map.converters['pet_type'] = PetConverter
bp.register_converter(PetConverter, 'integer')
@bp.route('/pet/')
class pet(MethodView):
@bp.response(PetSchema, description="get pet by id")
def get(self, pet):
return pet
```
this generates api documentation that shows a url of the style `get /pet/{pet}`
Ideally I'd like the api documentation to show as `get /pet/{pet_id}`
If I change the route decorator to use `/pet/` I'm then forced to use the variable name pet_id in my get method but it's actually a Pet object.
Perhaps the blueprint register converter could include a "reverse-formatter" argument or or callable something like:
```python
bp.register_converter(PetConverter, 'integer', varname_mangler=lambda x: f'{x}_id')
```
or more similar to flask_marshmallow's url_for:
```python
bp.register_converter(PetConverter, 'integer', varname_formatter='_id')
```
where my assumption would be that `` is a library defined constant stand in for the original variable name in the route so the library code is literally just:
```python
actually_reported_varname = varname_formatter.replace('', original_varname)
```
the callable is probably a nicer solution because it doesn't require the library constant so it's /slightly/ more flexible but either option would be a nice improvement
Contributor guide
Research direction
Start by tracing bp.register_converter and the route declaration using the PetConverter, then inspect how the generated API documentation derives its path parameter names. Compare the documented name with the argument passed to the get method. Done means a supported naming approach is decided and documented or implemented, with coverage for converter-backed parameters.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- flask, openapi, python
- Domain
- api, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 28/100