$接口文档$

【一】接口文档

【1】什么是接口文档

• 大白话：接口文档就是当你写前后端分离的时候，你需要让前端的人，知道你这个接口是干嘛的才好进行开发，及其后期的维护

• 写接口人负责写接口文档

• 比如：你写好了一个接口，但是前端要用，你只给他他也不会用，他也不知道这个接口是干嘛的，接收什么请求，用什么编码格式等等。

【2】在哪编写接口文档

• 通常在公司中

  • 使用world编写，放在公共平台上

  • 使用md编写---就是你的typora

  • 第三方平台编写：showdoc

  • 在大公司中：公司自己编写的

  • 基于开源的使用：YAPI百度开源

    • https://zhuanlan.zhihu.com/p/366025001

【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）
	-接口解释
	-地址
    -请求方式
    -请求参数：地址，头，体   参数说明，是否必填
    -返回示例：字段解释
    -错误码