自动生成接口文档
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、文档描述说明的定义位置
- 单一方法的视图，可以i直接使用视图类的文档字符串，如：
class BookListView(ListAPIView):
"""
返回所有图书信息
"""
- 包含多个方法的视图，在类视图的文档字符串中，分开方法定义，如:
class BookListAPIView(ListAPIView):
"""
get:
返回所有图书信息
post:
新建图书
"""
- 对于视图集
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',
}
注意：
- 视图集ViewSet中的retrieve名称在接口文档中叫做read
- 参数的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':'出版社'
}
}