【13.0】DRF之接口文档

【一】引入

• 后端把接口写好后
  • 登录接口
  • 注册接口
  • 查询所有图书带过滤接口
• 前端人员需要根据接口文档，进行前端开发
• 前后端需要做对接----> 对接第一个东西就是这个接口文档---> 前端照着接口文档开发

• 后端编写接口：

  • 后端团队负责设计和实现系统中的各个接口，根据业务需求完成登录接口、注册接口和查询所有图书(带过滤)接口等。
  • 接口的设计应考虑到安全性、可用性和高性能等方面的因素，并遵循一致的命名规范和参数传递方式。

• 编写接口文档：

  • 在后端接口开发完成后，需要编写接口文档以便前端开发人员了解接口的使用方法、参数和返回值等信息。
  • 接口文档应该具备清晰的结构和详细的描述，以便前端团队准确理解和使用接口。
  • 接口文档中可以包括接口的URL、请求方法、入参、出参、错误码、注意事项等内容。

• 前端根据接口文档进行开发：

  • 前端开发人员根据接口文档进行前端开发工作。
  • 他们通过阅读并理解接口文档，了解每个接口的功能和使用方式。
  • 接口文档提供了请求的URL、请求方法(如GET、POST)、需要传递的参数、参数格式和参数校验规则等信息，前端工程师可以据此编写前端代码，调用相应的接口。

• 前后端对接：

  • 在前后端对接过程中，前端开发人员需要根据接口文档与后端团队进行沟通和协商。
  • 他们可以将自己根据接口文档开发的前端代码提供给后端团队进行测试和联调。
  • 这个过程中可能需要讨论接口的使用方式、参数传递方式、数据格式等问题，以确保前后端的接口对接顺利进行。

• 总结来说:

  • 后端编写接口后，前端开发人员根据接口文档进行前端开发工作。
  • 接口文档是前后端对接的重要依据，能够准确传达后端接口的设计和使用方法，帮助前端团队在开发过程中与后端团队进行有效的沟通和协作。
  • 这样的流程可以确保前后端开发工作的高效和一致性。

【二】接口文档的编写形式

• 接口文档是在项目开发中非常重要的一部分
  • 用于描述和记录系统中各个接口的使用方式、参数、返回值以及其他相关信息。

• world，md，编写,大家都可以操作，写完放在git，公司的文档管理平台上

• 第三方的接口文档平台(收费)

  • https://www.showdoc.com.cn/

• 公司自己开发接口文档平台

• 公司使用开源的接口文档平台，搭建

  • YAPI：百度开源的

• 项目自动生成接口文档

  • coreapi
  • swagger

• 使用Markdown(md)格式编写：

  • Markdown是一种轻量级标记语言，被广泛应用于文档编写。
  • 使用Markdown格式编写接口文档具有简洁明了、易于编辑和查看的优点。
  • 编写完成后，可以将Markdown文档放置在Git等版本控制工具中，或者上传至公司的文档管理平台，方便团队内部协作和版本控制。

• 第三方接口文档平台：

  • 有一些收费的第三方接口文档平台可供选择
  • 例如ShowDoc(https://www.showdoc.com.cn/)。
  • 这些平台通常提供了丰富的文档编辑和管理功能，如可视化编辑、在线预览、权限管理等，能够帮助团队更高效地编写和维护接口文档。

• 公司自己开发接口文档平台：

  • 为满足具体业务需求，一些企业会选择自己开发接口文档平台。
  • 通过开发适用于内部使用的接口文档管理系统，可以更好地满足企业的定制化需求，并与其他内部系统进行集成，提高文档管理的便捷性和灵活性。

• 使用开源接口文档平台：

  • 另一种选择是使用开源的接口文档平台，如YAPI(百度开源的)。
  • 这些平台提供了接口管理、文档编写、权限控制等功能，并且可以在企业内部搭建，自主管理数据。
  • 开源平台通常具备良好的扩展性和可自定义性，可以根据具体需要进行二次开发和定制。

• 项目自动生成接口文档：

  • 为了减少手动编写接口文档的工作量，一些工具可以自动生成接口文档。
  • 其中比较常用的有CoreAPI和Swagger。
    • CoreAPI可以通过注释方式生成文档
    • 而Swagger可以通过接口描述生成功能详尽的文档，并提供可交互的API页面。
  • 这样的工具使得文档更新更加方便快捷，并且保证文档的及时性和准确性。

【三】使用coreapi自动生成接口文档

【1】安装coreapi库

• 首先需要使用pip命令安装coreapi库
  • 可以在命令行中运行pip3 install coreapi来完成安装。

pip3 install coreapi

【2】加一个路由

• 在项目的urls.py文件中，引入include_docs_urls函数，并将其添加到路由列表中。
• 例如，可以添加以下代码：

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

• 这样，当访问http://127.0.0.1:8000/docs/时，将会显示接口文档的页面，其中的标题可以根据实际情况进行修改。

【3】在视图类上加注释

• 为了使接口文档更加详细和清晰，需要在每个视图类上添加注释。
• 注释可以包含接口的功能描述、参数说明、返回结果等信息。
• 这些注释将会被coreapi自动解析生成接口文档。

【4】配置文件中配置

• 配置文件中配置DEFAULT_SCHEMA_CLASS：
  • 在项目的配置文件中(一般是settings.py)，找到REST_FRAMEWORK配置项，并将DEFAULT_SCHEMA_CLASS设置为'rest_framework.schemas.coreapi.AutoSchema'，这样在生成接口文档时将会使用coreapi自动生成的Schema来展示接口信息。

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
    ...
}

【5】表模型或序列化类的字段上写 help_text

• 为了在接口文档中显示字段的介绍信息，可以在表模型或序列化类的字段上添加help_text属性。
• help_text内容将被自动解析并展示在接口文档中。

【6】访问地址

• 完成以上步骤后，可以通过访问http://127.0.0.1:8000/docs/来查看自动生成的接口文档页面。

【四】docker-compose部署Yapi

【1】了解Docker Compose:

• Docker Compose是Docker官方推出的一个用于定义和运行多个Docker容器的工具。
• 通过使用Docker Compose，你可以使用一个单独的yaml文件来定义多个相关的服务，然后使用一条命令即可启动、停止和管理这些服务。

【2】准备Docker Compose文件：

• 首先，你需要创建一个名为docker-compose.yml的文件，并在其中定义Yapi的Docker镜像、容器名称、端口映射以及其他相关配置。
• 一个示例的docker-compose.yml文件如下所示：

version: '3'
services:
  yapi:
    container_name: yapi
    image: "ym/ym-yapi:latest"
    ports:
      - "3000:3000"
    volumes:
      - /yapi/config:/yapi/vendors

• 在上面的示例中，我们定义了一个名为yapi的service，使用了Yapi的Docker镜像"ym/ym-yapi:latest"。
• 我们将主机的3000端口映射到容器的3000端口，以便可以访问Yapi的Web界面。
• 并通过卷挂载，将主机的/yapi/config目录映射到容器的/yapi/vendors目录，以便持久化保存配置文件。

【3】执行Docker Compose命令：

• 在准备好docker-compose.yml文件后，在命令行中进入该文件所在的目录，并执行以下命令来启动Yapi服务：

docker-compose up -d

• 该命令会根据docker-compose.yml文件的定义，启动Yapi服务。参数"-d"表示以守护进程方式运行，即在后台运行。

【4】访问Yapi Web界面：

• 一旦Yapi容器启动成功，你就可以通过浏览器访问Yapi的Web界面。
• 在上面的示例中，你可以通过访问"http://localhost:3000"来访问Yapi。

【5】注意事项：

• 在执行docker-compose命令之前，确保已经安装了Docker和Docker Compose，并拥有执行权限。
• 在Docker Compose文件中，可以定义其他依赖服务，比如数据库等，并且可以按照需要进行配置。
• 根据实际情况，你可能需要修改Docker镜像的名称和版本号，并调整端口映射和卷挂载的路径。

【6】总结来说

• 使用Docker Compose部署Yapi可以简化整个部署过程，提高部署效率并保证环境一致性。
• 通过合理的配置和管理，可以轻松地启动和停止Yapi服务，并通过Web界面进行操作和管理。

【补充】什么是mock数据

【1】介绍

• Mock数据是在软件开发过程中使用的一种方式，它用于模拟真实数据源的数据，并且具有相似的数据结构和字段。

• Mock数据通常被用作在实际的数据源不可用或者无法获得时进行开发、测试和演示。

• Mock数据的主要目的是在软件开发的早期阶段就提供可用的虚拟数据，以便开发人员可以在没有实际数据的情况下进行系统的构建和测试。

【2】它可以用于以下几个方面：

• 前端开发：

  • 在前端开发中，当后端接口还未完成或者不可用时，可以使用Mock数据来模拟接口的返回数据，使前端开发人员能够独立进行开发和测试。

• 接口测试：

  • 在进行接口测试时，如果需要模拟特定的输入和输出场景，可以使用Mock数据来模拟接口的返回结果，以验证代码的正确性和处理能力。

• UI设计和演示：

  • Mock数据可以用于创建虚拟的用户界面，以展示产品的功能和交互效果。

  • 这对于产品设计师、项目经理和客户来说都是非常有用的，可以提前预览和审查产品的外观和行为。

• 性能测试：

  • 在某些性能测试场景中，可能需要模拟大量的数据来模拟真实的负载情况。
  • 使用Mock数据可以快速生成大量的虚拟数据，以评估系统的性能和稳定性。

【3】使用Mock数据的主要优点是：

• 快速开发和测试：

  • Mock数据能够提供可用的虚拟数据，使得开发人员和测试人员能够在没有完整的系统和真实数据的情况下进行工作。

• 独立开发和测试：

  • Mock数据允许前后端团队并行开发，以提高整个开发过程的效率。

• 真实数据的保护：

  • 使用Mock数据可以保护真实数据源中的敏感信息，避免因为开发和测试而导致真实数据泄露的风险。

【4】总之

• Mock数据是在软件开发过程中用于模拟真实数据的一种技术，它提供了一种快速、可靠和独立的方式来进行开发、测试和演示。