本文共 3382 字，大约阅读时间需要 11 分钟。

简介

django rest_framework 自动生成文档的功能，能够很好的给前端提供帮助，在文档中可以看到api的参数和其提供的功能信息，并且还能够在上面直接测试api接口。

配置

urls.py

from rest_framework.documentation import include_docs_urlsurlpatterns = [    ...    url(r'^docs/', include_docs_urls(title='My API title'))]

即可使用该url对文档的访问

自定义文档

虽然可以自动生成文档，但是不是很完善，所以需要自定义写文档。

schema

通过改写AutoSchema来完成自定义文档。

实现

方法一

get_link是AutoSchema中的函数. 重写get_link函数，对文档中的每个字段的说明进行改写。

集成AutoSchema，在__init__初始化params_desc_dict参数，该参数包含文档中字段对应的注释，然后在get_link对该参数进行解析，并替换字段注释.

class BaseSchema(AutoSchema):    """    自动生成的文档会有缺失，或者是因为可读性比较差。所以需要对文档中的字段进行自定义注解。    该类是通用的对文档中的get、post、put、delete、patch进行注释。    是在已有字段的基础上修改注释.        `get`是对get中的字段进行注解说明。    `other`是`post`、`put`、`delete`、`patch`        例子:        {            "get": {                "字段名": "对该字段进行注释"            },            "post": {                "字段名": "对该字段进行注释"            }        }    """    def __init__(self, manual_fields=None, params_desc_dict=None):        self.params_desc_dict = {
               "get": {
                   "page": "当前页码",                "page_size": "每一页显示的行数. 默认传 10条"            },            "other": {
               }        }        if params_desc_dict:            if 'get' in params_desc_dict:                self.params_desc_dict['get'].update(params_desc_dict['get'])            if 'other' in params_desc_dict:                self.params_desc_dict['other'].update(params_desc_dict['other'])        super(BaseSchema, self).__init__(manual_fields)    def get_link(self, path, method, base_url):        link = super(BaseSchema, self).get_link(path, method, base_url)        fields = []        params_method = 'get' if method.lower() == 'get' else 'other'        for field in link.fields:            if field.name in self.params_desc_dict[params_method].keys():                field = field._replace(                    schema=coreschema.String(description=self.params_desc_dict[params_method][field.name]))            fields.append(field)        return coreapi.Link(            url=link.url,            action=link.action,            encoding=link.encoding,            fields=fields,            description=link.description        )periodictaskSchema = BaseSchema(params_desc_dict={
       'other': {
           "crontab": "定时crontab. json。 包含的字段有: minute, hour, day_of_week, day_of_month, month_of_year",        "name": "该定时任务名称",        "task": "模板任务名",        "args": "传递给任务模板参数. 数组",        "kwargs": "传递给任务模板参数. json字符串",        "queue": "将任务放在哪个队列中.",        "enabled": "是否开启该任务. True or False. 默认为True",        "description": "定时任务说明"    }})

在view中绑定自定义的schema

class PeriodictasksViewSet(viewsets.ModelViewSet):    queryset = PeriodicTask.objects.all()    serializer_class = PeriodictaskSerializer    schema = periodictaskSchema

方法二

如果只是普通的APIView的话，直接在AutoSchema中添加字段即可。

databaseInfoSchema = AutoSchema(manual_fields=[    coreapi.Field(name="db", required=True, location="query",                  schema=coreschema.String(description="数据库host, normal或者sub")),    coreapi.Field(name="database", location="query", schema=coreschema.String(description="数据库")),    coreapi.Field(name="table", required=True, location="query", schema=coreschema.String(description="数据库表"))])

绑定自定义schema

class DataBaseInfo(APIView):    schema = databaseInfoSchema    def get(self, request):        pass

location

转载地址：http://uakjn.baihongyu.com/