OpenAPI Schema should support custom operationId on methods

[HT154]

Checklist

• I have verified that that issue exists against the master branch of Django REST framework.
• I have searched for similar issues in both open and closed tickets and cannot find a duplicate.
• This is not a usage question. (Those should be directed to the discussion group instead.)
• This cannot be dealt with as a third party library. (We prefer new functionality to be in the form of third party libraries where possible.)
• I have reduced the issue to the simplest possible case.
• I have included a failing test as a pull request. (If you are unable to do so we can still accept the issue.)

Steps to reproduce

1. Set up a view
2. Add post and get methods

Expected behavior

I can override generated List, Retrieve, or Create actions on a per-method basis

Actual behavior

I'm stuck with the generated names

Use case

I have a login endpoint that redirects users to an external SSO service. For legacy reasons, this must support GET and POST requests. When the OpenAPI schema is generated (with rest_framework.schemas.openapi.AutoSchema), I end up with two operations on the same path (less than ideal, but acceptable) and non-sensical actions (bad). I'd like to instead have the operation IDs GetLogin and PostLogin.

[carltongibson]

Hi @HT154.

So, what's actually generated vs what'd desired? (Just the snippet is fine.)

Then can you override get_operation() or _get_operation_id() to give you the result you want?
(What does your subclass look like?)

[xordoquy]

At some point, one may want to override a specific view's operation id and it doesn't feel right to include a check on the class view inside _get_operation_id() to get that customization.
My though about the schema generation is that it may lack some hooks to customize things on a per view basis to escape the autogeneration.

[carltongibson]

Right! Almost certainly. But I'm not sure what those hooks are/should be prior to people using the generation, creating some subclasses and seeing the patterns that emerge.

We added API for the CoreAPI version thinking "this is what people need" and I don't think it saw any use at all. Thus, I'd rather keep it simple for the first version and let people show us subclasses that do more. We can then bring it in.

Unless somebody can confidently predict the required API...

[carltongibson]

First guess, an AutoSchema subclass here would just look like this:

LoginViewSchema(AutoSchema):
    def _get_operation_id(self, path, method):
        if method == 'POST'
            return 'PostLogin'
        else: 
            return 'GetLogin'

Then:

class LegacyLoginView(APIView):
    schema = LoginViewSchema()
    ...

That looks pretty clean to me (for a first pass, where we don't know the common required customisations).

[xordoquy]

oh, didn't know you could have a per view AutoSchema. Seconding you then.

[carltongibson]

Yeah... (This was the same design as introduced back in v3.7, except without the guessed extra API).

The idea is:

• Schema level customization: subclass SchemaGenerator.
• Per-view customization: subclass AutoSchema (and attach per-view)

Maybe there's some declarative API to be added in a 3.10.1 or 3.10.2, but I want that to be based on actual patterns.

Doc updates are in #6668

[HT154]

I'm going to proceed with subclassing the relevant schema classes for my purposes, but here are the modifications I've wanted to make so far:

• The one mentioned in this issue: customizable operation IDs - default CRUD operation names aren't applicable for everything. I think a decorator around view methods/functions would be the best API
• Ability to override serializers for requests and responses (independently) - Example: a view that takes a path parameter and no body data and kicks off a background task, returning info about that task (ID, location, etc.)
• Doc-comments as descriptions for paths and operations - View- and method-level docs are definitely a must

I think most or all of these should be included upstream. I'm happy to open issues for the others if you feel it's appropriate, or if this should be implemented as a separate package, go ahead and close this.

[carltongibson]

The CoreAPI stuff already did descriptions from docstrings. That could be ported very easily. (A quick PR there would be most welcome!)

There’s hooks for both request body and responses in AutoSchema, so adjusting the serialiser there would be easy enough. (How you’d generalise that would be interesting to see.)

Best bet is to create what you need and put it up as a repo/package that we can look up, and maybe yes there could be stuff to bring in.

(Initially a bit 😬 about decorators, vs just saying “create a subclass” but it’s much clearer once there’s actual code in play.)

I’ll leave this open for a few days just in case people want to comment.

[HT154]

Unfortunately, my employer requires legal approval for all public code sharing :(

I might be able to post my implementation in 4-8 months, but I can/will report back with my progress on this

[carltongibson]

Well, perhaps you can still post the kind of thing you end up with, rather than the actual code itself. No worries though. 🙂

[HT154]

Other potential improvements:

• Surfacing auth, permissions, and throttle info
• Some way to specify request header parameters (pass it a serializer?)
• Ability to add arbitrary serializers as definitions not associated with views (maybe via django settings key?), eg. for message broker message schemas

[HT154]

Here's what I've got for custom operation IDs so far:

# this only works for method on class-based views
def operation_id(op_id):
    def wrapper(f):
        f.operation_id = op_id
        return f
    return wrapper

@api_view(('POST',))
def my_view(...)
    return Response(...)

my_view.cls.post.operation_id = 'MyOperation'

class LoginView(APIView):

    @operation_id('LoginPost')
    def post(self, request):
        return Response(...)

    @operation_id('LoginGet')    
    def get(self, request):
        return self.post(request)

If @api_view added support for this decorator, it would work on function-based views as well.

Here's an alternate approach, but not one I could reasonably implement in my own code without some serious overhaul:

@api_view(('POST',))
@schema(AutoSchema, operation_id='OpID')
def view(...)
    return ...

@api_view(('POST',))
@schema(operation_id='OpID')
def view(...)
    return ...

If no actual schema arg is provided to @schema, then the default would be used.