marshmallow-code / marshmallow-code/flask-smorest

renaming args in api spec

Open
#120 6 comments 1 reaction 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.