Rails 【新工具上线】yapi_check——让 API 验证不再头疼!

ThxFly · 2024年03月13日 · 292 次阅读

YAPI 是一款比较好用的接口文档管理工具。可见 V 站讨论 https://www.v2ex.com/t/697920

Gem: https://github.com/shootingfly/yapi_check

大家好!

在日复一日的开发工作中,我们常常面临着 API 文档与代码不一致的挑战。无论是确保 API 请求的格式正确,还是验证返回数据的准确性,这一切的工作都显得繁琐且耗时。但现在,有了新工具 yapi_check,这一切都将变得简单和高效!

YapiCheck 说明

yapi_check 是什么?

yapi_check 是一款专为 Rails 开发者设计的 Gem 包,旨在提供一个简洁、易用的 YAPI 验证解决方案。它能帮助你轻松校验 YAPI 请求与响应,确保数据的准确性,从而大幅提高开发效率。

yapi_check 能做什么?

  1. 自动验证 YAPI 请求和响应:通过简单的配置,yapi_check 能够自动验证 YAPI 的请求和响应格式,确保它们符合预期。
  2. 详细的错误报告:当 API 验证失败时,yapi_check 能够提供详细的错误报告,帮助你快速定位问题所在。
  3. 简化测试流程:通过自动化的验证流程,yapi_check 可以帮助你减少手动测试的工作量,让测试更加高效。

如何开始使用?

开始使用 yapi_check 非常简单,只需要几个步骤:

  1. 在你的 Gemfile 中添加gem 'yapi_check'
  2. 运行bundle install安装。
  3. 根据 yapi_check 的文档设置你的 API 验证规则。
  4. 开始享受轻松、高效的 API 验证体验!

技术原理概述

在现代 Web 开发中,API 的准确性和一致性对于应用的稳定性和用户体验至关重要。我们的 Gem,yapi_check,利用了 YAPI 项目开放的 OpenAPI,这使得获取接口文档的元数据(如参数类型等)成为可能。得益于 Ruby 的声明式语法特性、Rails 的惯例式编程,以及 method_source 的支持,我们可以轻松读取和规范化 Rails 项目的源码。通过设定精准的正则匹配规则,yapi_check 能够有效地比对和确保项目的 API 接口与其文档的一致性。

工作流程

  1. 配置获取: 首先,从 YAPI 项目配置中获取项目的 token。
  2. 接口列表调用: 使用 token 调用接口列表 API,(可选) 筛选指定迭代版本下的接口,并通过路径获取接口 ID。
  3. 获取接口详情: 通过接口 ID,获取并提取接口的详细信息,包括路径、请求参数类型和响应参数类型。
  4. 请求参数校验: 根据接口路径,提取 controller 对应 action 中的请求参数字段、参数类型、是否必填,并进行参数正确性比对。(注:非 JSON 参数的类型比对不在此范围内)
  5. 响应参数校验: 提取 action 对应 jbuilder 的响应参数和类型,进行响应参数的正确性比对。
  6. 报告生成: 生成并输出详细的排查报告,指出可能的不一致之处。
  7. 自动化执行: 全过程可通过 rake 任务自动化执行,提高效率和准确性。

使用注意

为了确保 yapi_check 的兼容性,请注意以下最佳实践原则:

  1. 参数校验: 我们推荐使用 lucky_param 进行参数校验,以确保参数的准确性和安全性。
  2. 响应格式: 应通过 jbuilder 来管理响应输出,确保响应的 JSON 数据被正确地封装在"data"对象中,例如{"data": {}}
  3. 文档管理: 我们采用 YAPI 进行接口文档管理。对于需要非接口类文档,请在接口名称的开头明确标注"[接口说明]"。
  4. 自定义修改: 如果您的项目实践与上述不完全一致,您可以 fork 此项目并进行必要的修改,之后欢迎提交 MR 以共享您的改进。

请注意,目前我们不支持布尔型参数的校验,布尔型应都用整型参数替代,以支持可能的扩展。

暂无回复。
需要 登录 后方可回复, 如果你还没有账号请 注册新账号