阿沃卡多语Name
OpenAPI spec寄存器配置和目录的又一验证器.
国家预防机制:https://www.npmjs.com/package/@azure/vocado
概览
Avocado验证文件夹结构和配置.
Avocado可以被集成到Azure管道来验证OpenAPI spec寄存器. 例如,Avocado被使用为 Azure/azure-rest-api-specs 当新的拉动请求被创建时, 它会自动被 Azure DevOps 管道触发 .
阿沃卡多主要功能如下:
- 对于给定的目录验证是否存在
specification过滤器readme.md下划线specification文件夹. - 验证是否
readme.md是自定义的特定文件,必须包含see https://aka.ms/autorest - 验证是否
swagger file是有效的json文件,并检查所有引用json文件( 编号referenced json以 json 对象标记的文件有密钥名称"$ref") (中文(简体) ). - 校验文件夹是否有未引用的文件 .
swagger file必须引用readme.md或其他类型swagger file。 。 。 . - 验证是否
swagger file有个通知和警告 详见: 民事裁判所 - 验证每个 RP 文件夹是否包含 SDK 生成的 readme 文件 .
如何使用
安装
npm install -g @azure/avocado
使用量
avocado -h显示帮助消息avocado验证当前目录avocado -d <my-folder-path>验证<my-folder-path>目录avocado -d <my-folder-path> --excludePaths 'common-types'校验文件夹并排除“ 常见类型” 的错误
示例
- 运行全部规格 : 清除还原
azure/azure-rest-api-specs在文件夹中运行“ vocado ”azure/azure-rest-api-specs。 。 。 . - 运行单个服务规格: 创建文件夹
specification并移动您的服务规格文件夹specification运行"vocado"
如何解决错误
JSON 平面
级别: 错误
要解决 json 解析错误, 您需要确保 json 格式是有效的 .
否 JSON FILE FOUND
级别: 错误
Readme 文件引用了一个不存在的json文件. 要解决错误, 您需要检查 json 文件是否存在 .
(原始内容存档于2017-10-21) (英语). UNREFERENCE JSON FILE
级别: 错误
Json文件必须被readme输入文件部分或其他json文件所引用. Eg,实例 swagger 文件应该被主 swagger json 引用,对于 SDK 生成主 swagger ,应该被 readme 输入文件部分引用. 要解决错误, 您需要将非引用文件放置到合适的位置 .
失忆了
级别: 错误
每个资源提供者文件夹必须有一个下游SDK生成所需的readme文件. 要解决错误,需要创建包含SDK生成配置的readme文件.
不为人知
级别: 错误
资源提供者文件夹中的每个读取器都应遵循自动降标格式。 要解决错误, 请检查 readme 块引用是否包含 see https://aka.ms/autorest 从字面上说.
密码:
级别: 错误
Swagger json 文件 api 版本必须与其文件路径一致 。 斯瓦格可以定义 swagger 2.0 基本结构 包含 api 版本。 要解决错误, 您需要修改您的 swagger 文件位置或 swagger 文件 api 版本, 以使两者一致 .
中心-资源
级别: 警告
要解决循环参考问题,应当打破循环链.
示例 a.json - > (中文) b.json- > (中文)c.json
// a.json
{ "$ref": "b.json" }
// b.json
{ "$ref": "c.json" }
// c.json
{ "$ref": "a.json" }
graph TD
A((a.json))-->B((b.json))
B-->C((c.json))
C-->A
模拟 API VERSION
级别: 错误
默认标记只应包含一个API版本.
要解决这个错误, 您应该为您服务中的所有资源类型添加一个新的一致的版本, 并将字段复制到当前版本文件夹中 .
评分( F)
级别: 警告
管理平面 swagger JSON 文件与其文件夹路径不符 。 确保位于资源管理文件夹中的管理平面 swagger
要解决此警告, 您应该确保位于资源管理文件夹中的管理器平面 swagger .
错过 APIS IN DEFAULT TAG
级别: 错误
这个 默认 API 版本标签( 可见于 Basic information 节次 自动Rest 配置文件 (README文件)应当包含所有API路径.
API 路径 : ${0} 在任何 OpenAPI 中都没有 .json 包含在默认标签中的路径列表中列出的文件,如 相关 Tag: 节 在自动恢复配置文件(README文件)中.
修复此错误包括 OpenAPI .json 默认 API 版本标签路径列表中的文件路径( 在 相关 Tag: 节包括缺失的 API 路径.
重要性:错误可能指向之前的API版本. 这并不意味着这是假阳性来啊! 这意味着之前的API版本有一个API路径在默认API版本中缺失.
Avocado 正常公关失败的常见情况数字 :
- 由于外壳不匹配, API 路径往往从默认 API 版本中缺失; 例如, 新 API 版本中的路径
resourceGroups在其中,而前一个有resourcegroups. 见下文实例. - 如果阿沃卡多报告你错过了一条路 故意贬值 或者说 故意删除 但API版本是公开发布的(GA,通用可用,不预览中),您需要先获得 突破变更委员会审批. 跟踪步骤1的突破性改变过程 此图如果您在先前的公关中已经获得这种批准,请遵循 压制指南提到你确定的情况.
已知的阿沃卡多报告虚假阳性的情况: Avocado可能错误地报告以下两种情景中的失败:
如果你正在处理其中一种情况 压制指南提到你确定的情况.
当此错误可以被压制时: 如果缺失的 API 路径被贬值, 您可以压制这个错误 。 循此[先入后入导].
例如,详细分析这类错误的发生,见这些GitHub评论:
(简体中文)
级别: 错误
这个 默认 API 版本标签( 可见于 Basic information 节次 自动Rest 配置文件 (README文件)不包含给定的OpenAPI的最新API版本 .json 文档.
要纠正这个错误,请确保 .json 最晚API版本路径的文件包含在默认标签路径列表中,在 相关 Tag: 节 在自动恢复配置文件(README文件)中.
或者,通过编辑 API 版本标签,将默认的 API 版本标签改为有效的标签 Basic information 节.
例如,详细分析这种错误的发生,见 此 GitHub 注释。 。 。 .
(原始内容存档于2013-10-12). MULTIPLE DEFAULT TAGS
级别: 错误
Readme 文件有多个默认标签.
期望是只有一个默认标记,这会导致一个SDK包. 在同一RP的不同服务资源上发布单独的SDK软件包,不妨考虑采用 服务组的文件夹结构,它支持每个子文件夹下的 readme 配置文件.
评分( T)
级别: 错误
Typec 文件在资源管理或数据平面文件夹中不允许使用.
以修此错. 您应该将 TypeSpec 文件移动到 TypeSpec 文件夹 .
捐款
该项目欢迎各方的贡献和建议。 大多数捐款要求您同意 撰稿人许可协议(CLA)宣布,你有权并且实际上确实给了我们 有权使用您的贡献。 详情请访问 https://cla.microsoft.com (中文(简体) )。 。 。 .
当您提交拉动请求时, CLA 机器人会自动确定您是否需要提供 a CLA并适当装饰公关(例如标签、评论)。 只要听从指示 由机器人提供。 你只需要用我们的CLA 一次就能完成.
该项目通过了 Microsoft 开源行为守则。 。 。 . 更多信息见 《行为守则》 或者说 联系人 打开码@ microsoft.com 并附上任何其他问题或评论.