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 以共享您的改进。

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