DRF自动生成接口文档

REST framework可以自动帮助我们生成接口文档。

接口文档以网页的方式呈现。

自动接口文档能生成的是继承自APIView及其子类的视图。

REST framework接口文档的生成需要coreapi库的支持

 设置接口文档访问路径

在总路由中添加接口文档路径

from rest_framework.documentation import include_docs_urls


urlpatterns = [
    path('docs/',include_docs_urls(title='xx接口文档')),
    path('admin/', admin.site.urls),
   
]

文档描述说明的定义位置

1，单一方法的视图，可以直接使用类视图的文档字符串

class BookListView(generics.ListAPIView):
    """
    返回所有图书信息.
    """

2， 包含多个方法的视图， 在类视图的文档字符串中，分开方法定义

class BookView(ViewSetMixin,ListAPIView,CreateAPIView):
    '''
    list 返回所有图书信息
    create 新建图书
    '''

3，对于视图集ViewSet,仍在类视图的文档字符串中分开定义，但是应使用action名称区分

class BookInfoViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet):
    """
    list:
    返回图书列表数据

    retrieve:
    返回图书详情数据

    latest:
    返回最新的图书数据

    read:
    修改图书的阅读量
    """

访问接口文档网页

浏览器访问 127.0.0.1:8000/docs/，即可看到自动生成的接口文档。

 报错情况

#AttributeError: 'AutoSchema' object has no attribute 'get_link'
REST_FRAMEWORK = {
 'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
    # 新版drf schema_class默认用的是rest_framework.schemas.openapi.AutoSchema

}

 说明：

1， 视图集ViewSet中的retrieve名称，在接口文档网站中叫做read

2,参数的Description需要在模型类或者序列化器类的字段中以help_text选项定义，

class Student(models.Model):
    ...
    age = models.IntegerField(default=0, verbose_name='年龄', help_text='年龄')
    ...

 或

class StudentSerializer(serializers.ModelSerializer):
    class Meta:
        model = Student
        fields = "__all__"
        extra_kwargs = {
            'age': {
                'required': True,
                'help_text': '年龄'
            }
        }