Document how to use drf-spectacular with function-based views

[johnthagen]

The docs say:

https://github.com/tfranzel/drf-spectacular/blob/fb4c8410357b8a987991888d026167496165e95a/README.rst#drf-spectacular

@extend_schema decorator for customization of APIView, Viewsets, function-based views

But currently the documentation doesn't have any examples for how to use it with function-based views. This has led to stack overflow questions like:

• https://stackoverflow.com/questions/70549124/django-rest-framework-documenting-parameters-of-function-based-view-without-mod

It would be helpful for this use case to document some basic function-based examples, and if there are any supported ways to reduce manual boilerplate (like type hints?).

[johnthagen]

For those that might stumble upon this. Here is an example that could help:

@extend_schema(responses=MyConfigSerializer)
@api_view()
@permission_classes([AllowAny])
def my_configuration(request: Request) -> Response:
    """My Docs."""
    instance = MyConfig.get_solo()  # Using django-solo in this example.
    serializer = MyConfigurationSerializer(instance)
    return Response(serializer.data)

Register the function to a URL:

urlpatterns = [
    ...
    # Function-based view.
    path("api/my-configuration/", my_configuration, name="my-configuration"),
]

[tfranzel]

Hey @johnthagen,

I assumed this was kind of obvious. Explaining how @api_view works, i would say, is the responsibility of DRF's docs. From our side, its merely attaching @extend_schema just like with regular class-based views. Nothing super special from a user perspective and the tests contain dozens of examples of this usage pattern.

Maybe a FAQ entry? not sure where to put this ideally.

[johnthagen]

@tfranzel Yes, as I worked through this, a big part of the issue is actually what I perceive as a lack of documentation within DRF itself as well for function-based views.

Yeah, perhaps a FAQ entry is enough? I think just the fact that there weren't any examples was what made it harder to get started.

Worst case, I thought this issue's existence and my short example could be something someone else could find in the future.

[johnthagen]

Nothing super special from a user perspective and the tests contain dozens of examples of this usage pattern.

Perhaps point users to the tests if that is the best source of examples?

[tfranzel]

@api_view does some really funky stuff under the hood, which I had to learn when it came to parsing it. I believe very view people really understand the magic they are using there. Pretty sure the confusions stems from that.

Added a FAQ entry that may help.

Generally, virtually every (intended) usage pattern is covered in the tests. I tried making them compact, but finding a specific usage pattern in hundreds of tests is tricky in itself. Needle in a haystack you might say. I cannot really judge if people besides me are able to navigate the tests in meaningful way. I know where to look because I've written most of them. Have you used the tests like this?

[johnthagen]

@tfranzel That FAQ entry is great! I think we can call this issue closed now. Thanks!