drf接口文档

接口文档

接口编写已经写完了,需要编写接口文档，给前端的人使用

1. -请求地址
2. -请求方式
3. -支持的编码格式
4. -请求参数(get,post参数)
5. -返回格式示例

复制代码

在公司的写法

1）直接使用word或者md写
2）使用接口文档平台，在接口文档平台录入(Yapi（百度开源的自己搭建）,第三方平台(收费)，自己开发接口文档平台)

1. -https://www.showdoc.com.cn/item/index
2. - 不想花钱，没有能力开发，就使用开源的YAPI，   https://zhuanlan.zhihu.com/p/366025001

复制代码

3）项目自动生成：swagger，coreapi

1. -1 下载：pip3 install coreapi
2. -2 路由中配置：
3.         from rest_framework.documentation import include_docs_urls
4.         urlpatterns = [
5.             path('docs/', include_docs_urls(title='站点页面标题'))
6.         ]
7. -3 在视图类中加注释
8. -4 在配置文件中配置
9.         REST_FRAMEWORK = {
10.          'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
11.         }

复制代码

自动生成接口文档

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

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

1. pip install coreapi

复制代码

设置接口文档

在总路由中添加接口文档路径。
文档路由对应的视图配置为rest_framework.documentation.include_docs_urls，
参数title为接口文档网站的标题。

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

复制代码

文档描述说明的定义位置

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

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

复制代码

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

1. class BookListCreateView(generics.ListCreateAPIView):
2.     """
3.     get:
4.     返回所有图书信息.
6.     post:
7.     新建图书.
8.     """

复制代码

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

1. class BookInfoViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet):
2.     """
3.     list:
4.     返回图书列表数据
6.     retrieve:
7.     返回图书详情数据
9.     latest:
10.     返回最新的图书数据
12.     read:
13.     修改图书的阅读量
14.     """

复制代码

访问接口文档网页

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

注意要点

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

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

复制代码

或

1. class StudentSerializer(serializers.ModelSerializer):
2.     class Meta:
3.         model = Student
4.         fields = "__all__"
5.         extra_kwargs = {
6.             'age': {
7.                 'required': True,
8.                 'help_text': '年龄'
9.             }
10.         }

复制代码

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！