Edit parameter description for Django REST swagger and other issues

Question

I. I'm new to using Django REST Swagger for API documentation. I'm trying to understand how to edit a) 'Implementation Notes' and b) parameter descriptions. Image below -

Here's my viewset for the 'Crash' model.

class CrashViewSet(viewsets.ModelViewSet):
"""
retrieve: Get a single Crash instance

list: Get a list of all Crashes
"""
queryset = Crash.objects.all()
serializer_class = CrashSerializer
filter_backends = (SearchFilter,DjangoFilterBackend,OrderingFilter,)
search_fields = ('crash_id','crash_hr_short_desc','urb_area_short_nm','fc_short_desc',
                 'hwy_compnt_short_desc','mlge_typ_short_desc', 'specl_jrsdct_short_desc',
                 'jrsdct_grp_long_desc','st_full_nm','isect_st_full_nm','rd_char_short_desc',
                 'isect_typ_short_desc','crash_typ_short_desc','collis_typ_short_desc',
                 'rd_cntl_med_desc','wthr_cond_short_desc','rd_surf_short_desc','lgt_cond_short_desc',
                 'traf_cntl_device_short_desc','invstg_agy_short_desc','crash_cause_1_short_desc',
                 'crash_cause_2_short_desc','crash_cause_3_short_desc','pop_rng_med_desc','rd_cntl_med_desc')
filter_fields = ('ser_no','cnty_id','alchl_invlv_flg','crash_day_no','crash_mo_no','crash_yr_no','crash_hr_no',
                'schl_zone_ind','wrk_zone_ind','alchl_invlv_flg','drug_invlv_flg','crash_speed_invlv_flg',
                'crash_hit_run_flg',)
ordering_fields = '__all__'

I have made some edits to the DocString but don't quite understand how to proceed so as to get a more thorough descriptions of the endpoints and their fields. I tried going through the Django REST Swagger tutorial but I'm not given any direction on how to format the DOCSTRING. What's the best way to do this?

---

II. Another minor issue is that I want to get rid of the 'Django Login' button since this is public API. How do I do this?

---

III. What are some best practices for API documentation?

Petes

Answer 1

You can use the method_decorator to set both name and decorator. Additionally, you can describe your request body scheme and its description using the swagger_auto_schema decorator's request_body parameter.

@method_decorator(
name="get",
decorator=swagger_auto_schema(
    operation_summary="Get a list of all Crashes",
    operation_description="Get a list of all Crashes",
    request_body=openapi.Schema(
        type=openapi.TYPE_OBJECT,
        properties={"limit": openapi.Schema(type=openapi.TYPE_STRING, description="Limit")},
    ),
    responses={200: CrashSerializer},
))

Docs Ref

Either