本文共 1772 字,大约阅读时间需要 5 分钟。
REST framework可以自动帮助我们生成接口文档。
接口文档以网页的方式呈现。
自动接口文档能生成的是继承自APIView
及其子类的视图。
REST framewrok生成接口文档需要coreapi
库的支持。
pip install coreapi
在总路由中添加接口文档路径。
文档路由对应的视图配置为rest_framework.documentation.include_docs_urls
,
参数title
为接口文档网站的标题。
from rest_framework.documentation import include_docs_urlsurlpatterns = [ ... path('docs/', include_docs_urls(title='站点页面标题'))]
如果报错了下面的错误,说明我们缺少一个依赖,配置一下就行了
'AutoSchema' object has no attribute 'get_link'
配置:
REST_FRAMEWORK = { ... 'DEFAULT_SCHEMA_CLASS': "rest_framework.schemas.AutoSchema",}
1) 单一方法的视图,可直接使用类视图的文档字符串,如
class BookListView(generics.ListAPIView): """ get: 返回所有图书信息. post: 添加记录 """ #注意,这是在类中声明的注释,如果在方法中你声明了其他注释,会覆盖这个注释的
2)包含多个方法的视图,在类视图的文档字符串中,分开方法定义,如
class BookListCreateView(generics.ListCreateAPIView): """ get: 返回所有图书信息. post: 新建图书. """
3)对于视图集ViewSet,仍在类视图的文档字符串中封开定义,但是应使用action名称区分,如
class BookInfoViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet): """ list: 返回图书列表数据 retrieve: 返回图书详情数据 latest: 返回最新的图书数据 read: 修改图书的阅读量 """
浏览器访问 127.0.0.1:8000/docs/,即可看到自动生成的接口文档。
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-q7240NS5-1604824521621)(assets/接口文档页面.png)]
1) 视图集ViewSet中的retrieve名称,在接口文档网站中叫做read
2)参数的Description需要在模型类或序列化器类的字段中以help_text选项定义,如:
class Student(models.Model): ... age = models.IntegerField(default=0, verbose_name='年龄', help_text='年龄') ...
或 注意,如果你多个应用使用同一个序列化器,可能会导致help_text的内容显示有些问题,小事情
class StudentSerializer(serializers.ModelSerializer): class Meta: model = Student fields = "__all__" extra_kwargs = { 'age': { 'required': True, 'help_text': '年龄' } }
转载地址:http://lgqzi.baihongyu.com/