手摸手,带你用Django REST Framework撸接口系列十三(自动生成接口文档篇)

REST framework可以自动帮助我们生成接口文档。接口文档以网页的方式呈现。自动接口文档能生成的是继承自APIView及其子类的视图。

安装依赖

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

1
pip install coreapi

设置接口文档访问路径

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

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

参数title为接口文档网站的标题。

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

注册组件

1
2
3
4
# setting.py
REST_FRAMEWORK = {
'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
}

视图集方法注释方式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
class ArticleView(viewsets.ModelViewSet):
"""
文章列表视图类

list:
返回文章列表数据

create:
添加一篇文章

read:
查询一篇文章

update:
更新一篇文章

delete:
删除一篇文章
"""
pass

访问页面

总结

两点说明:

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

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

1
2
3
4
class Article(models.Model):
...
title = models.IntegerField(default=0, verbose_name='标题', help_text='文章的标题')
...

1
2
3
4
5
6
7
8
9
10
class ArticleSerializer(serializers.ModelSerializer):
class Meta:
model = Article
fields = "__all__"
extra_kwargs = {
'title': {
'required': True,
'help_text': '文章的标题'
}
}