Custom Documentation on API View

[TheBeardedTemplar]

Hey all,

I've recently upgraded to Django Rest Framework 3.8 and the
django-rest-swagger version I have been using no longer supports the
version, so I'm needing to update the way I'm doing documentation. I've
been using the YAML documentation style in DRF as follows and then
accessing it via a /docs/ endpoint:

class WidgetList(APIView):
permission_classes = (classes.IsAuthenticated,)

def get(self, request, format=None):
"""
Get a list of all widgets
Access: Authenticated
---
parameters:
- name: category
description: ID of widget category
type: integer
paramType: query
serializer: WidgetSerializer
responseMessages:
- code: 200
message: Widgets listed successfully
- code: 404
message: Widget not found
"""
#Logic to get response
return Response(serializer.data)

def post(self, request, format=None):
"""
Create a new widget
Access: Authenticated
---
serializer: WidgetSerializer
responseMessages:
- code: 201
message: Widget created
- code: 403
message: Insufficient rights to create widget
- code: 400
message: Bad request
"""
serializer = WidgetSerializer(data=request.data)

if serializer.is_valid():
serializer.save()
return Response(serializer.data, status=status.HTTP_201_CREATED)
return Response(serializer.errors,
status=status.HTTP_400_BAD_REQUEST)

However I'm now finding that DRF and Django Rest Swagger don't support
this. I've spent a few hours reading on Coreapi and OpenAPI and I'm having
trouble determining what exactly I have to do to get similar documentation.
Do I have to use DRF generics? Those work for some of my endpoints but some
of the endpoints we have are a bit too weird for the generics? Ideally I'd
be able to store all the logic related to documentation in the same file as
the views, but I'm willing to adjust the way I'm doing things.

Basically I have done some reading and am not sure if I'm missing a small
detail, or if I'm doing things completely wrong. I'd love some pointers on
how to get similar documentation. Note that I'm not attached to Django Rest
Swagger at all - a different tool isn't a problem.

Thanks!