自动生成接口文档

目录

• 1、安装依赖
• 2、设置接口文档访问路径
• 3、文档描述说明的定义位置

rest framework可以自动帮助生成接口文档

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

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

1、安装依赖

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

pip install coreapi

2、设置接口文档访问路径

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

文档路由对应的视图配置为rest_framework.documentation. include_docs_urls

from rest_framework.documentation import include_docs_urls
urlpatterns = [
    ...
    path('docs/',include_docs_urls(title='站点页面标题'))
]

3、文档描述说明的定义位置

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

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

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

class BookListAPIView(ListAPIView):
    """
    get:
    返回所有图书信息

    post:
    新建图书
    """

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

from rest_framework import mixins
from rest_framework.viewsets import GenericViewSet

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

   retrieve:
   返回图书的详情数据

   latest:
   返回最新的图书数据

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

最后浏览器中输入，http://127.0.0.1:8000/docs/，报错

需要在配置文件settings.py中设置如下:

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
    #默认用的是:  'rest_framework.schemas.openapi.AutoSchema',
}

注意：

1. 视图集ViewSet中的retrieve名称在接口文档中叫做read
2. 参数的Description需要在模型类或者序列化器类的字段中以help_text选项定义，如下:

class Book(BaseModel):
    id = models.AutoField(primary_key=True)
    name = models.CharField(max_length=32, verbose_name='书名', help_text='这里填写书名')
    price = models.DecimalField(max_digits=8, decimal_places=2, verbose_name='价格', help_text='这里填写书的价格')

或者

class BookModelSerializer(serializers.ModelSerializer):
    class Meta:
        list_serializer_class = BookListSerializer
        model = Book
        fields = '__all__'
        extra_kwargs = {
            'publish': {
                'required':True,
                'write_only': True,
                'help_text':'出版社'
            }   
        }