【一】接口文档
【1】什么是接口文档
-
大白话:接口文档就是当你写前后端分离的时候,你需要让前端的人,知道你这个接口是干嘛的才好进行开发,及其后期的维护
-
写接口人负责写接口文档
-
比如:你写好了一个接口,但是前端要用,你只给他他也不会用,他也不知道这个接口是干嘛的,接收什么请求,用什么编码格式等等。
【2】在哪编写接口文档
-
通常在公司中
-
使用world编写,放在公共平台上
-
使用
md
编写---就是你的typora
-
第三方平台编写:
showdoc
-
在大公司中:公司自己编写的
-
基于开源的使用:
YAPI
百度开源
-
【3】自动生成接口文档的步骤
-
drf
---借助于第三方生成-
coreapi
、drf-yasg
、drf-spectacular
-
-
fastapi
---自带接口文档
【4】coreapi
的使用
-
自动接口文档能生成的是继承自
APIView
及其子类的视图 -
1.安装
-
pip install coreapi
-
-
2.设置接口文档访问路径
-
在总路由中添加接口文档路径
-
# 文档路由对应的试图配置为: rest_framework.documentation.include_docs_urls
-
参数
title
为接口文档网站的标题 -
from rest_framework.documentation import include_docs_urls urlpatterns = [ ... path('docs/', include_docs_urls(title='站点页面标题')) ]
-
-
3.文档描述说明的定义位置
-
(1).单个方法的视图,可以直接使用类试图的文档字符串
-
class BookListView(generics.ListAPIView): """ 返回所有图书信息. """ queryset = book.objects.all() serializer_class = BookSerializer
-
-
(2).包含多个方法的视图类,在类视图类的文档字符串中,分开方法定义
-
class BookListCreateView(generics.ListCreateAPIView): """ get: 返回所有图书信息. post: 新建图书. """ queryset = book.objects.all() serializer_class = BookSerializer
-
-
(3).对于视图集
ViewSet
,仍在类视图的文档字符串中分开定义,当应该使用名称区分-
class BookInfoViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet): """ list: 返回图书列表数据 retrieve: 返回图书详情数据 latest: 返回最新的图书数据 read: 修改图书的阅读量 """ queryset = book.objects.all() serializer_class = BookSerializer
-
-
-
4.访问接口文档的网页路径
-
# 访问这个路径,即可看到自动生成的接口文档 127.0.0.1:8000/docs/
-
-
5.在配置文件中定义
REST_FRAMEWORK = { 'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema', # 新版drf schema_class默认用的是rest_framework.schemas.openapi.AutoSchema }
-
这是访问路径的样式
【5】使用showdoc
编写接口文档
-
访问地址:ShowDoc
-
可以直接导入postman文件,一键生成,但是有些地方需要进行修改
-
也可以直接手动创建
【6】接口文档的格式
# 接口文档规范(https://opendocs.alipay.com/open-v3/28d9fff7_alipay.trade.refund) -接口解释 -地址 -请求方式 -请求参数:地址,头,体 参数说明,是否必填 -返回示例:字段解释 -错误码