[RFC] Make code argument first positional in @response

I opened #193 2 months ago but didn’t get much feedback so I figured I’d open an RFC issue for more visibility.

Currently, status code defaults to 200, which is also Flask default.

    def response(
            self, schema=None, *, code=200, description=None,
            example=None, examples=None, headers=None
    ):

The proposal is to make code mandatory and first positional arg.

    def response(
            self, code, schema=None, *, description=None,
            example=None, examples=None, headers=None
    ):

The first motivation for this was to make the signature coherent with the long-awaited upcoming alt_response decorator (#159).

Obviously, this change breaks everyone’s code, but it is at worst a tedious find’n replace, no feature broken.

Pros

• In line with alt_response decorator.
• Nicer visually to have all the codes and schemas aligned.
• No real reason to have 200 as default, apart from alignment with Flask. In my typical REST API resource, only 3 endpoints out of 5 return a 200.
• Make it explicit to the user that a code will be added to the response and which one.

Cons

• Need to specify 200 more than half of the time while it could be the default.
• Need to change existing codebases.

I’m leaning towards moving on with this, but I can allow a little bit more time for feedback before I do so. It is not so much about counting 👍 and 👎 than letting users express specific concerns I might have overlooked.

[Anti-Distinctlyminty]

Yes, that was my instinct. In which case my vote is to just go ahead with this and @alt_response. The change is breaking, but minimal effort to fix, and I would greatly appreciate the ability to properly document all responses.

[lafrech]

Done.