编辑Django REST swagger等问题的参数描述

Question

我。我刚开始使用 Django REST Swagger 来获取 API 文档。我试图了解如何编辑 a)“实施说明”和 b) 参数描述。下图 -

这是我对“崩溃”模型的看法。

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__'

我对 DocString 进行了一些编辑，但不太明白如何继续以获得端点及其字段的更全面的描述。我尝试浏览 Django REST Swagger 教程，但没有给出任何有关如何格式化 DOCSTRING 的指示。最好的方法是什么？

---

二.另一个小问题是我想去掉“Django Login”按钮，因为这是公共 API。我该怎么做呢？

---

三． API 文档的最佳实践有哪些？

Answer 1

您可以使用

method_decorator

来设置

name

和

decorator

。此外，您可以使用

swagger_auto_schema

装饰器的

request_body

参数来描述您的请求正文方案及其描述。

@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},
))

文档参考