在openapi中的两个不同路径之间共享operationId

Question

首先，我想为我的英语道歉。这不是我的错，而是西班牙的教育体系：D。

我刚刚开始进行openapi的迁移，需要您的帮助。 我喜欢使用引用相同operationId的不同路径。 我用一个例子解释了它：

paths:
  "/my-path/my-resource":
    get:
      tags:
        - my-api
      operationId: getMyResource
      responses:
         ...
         [omitted]
         ...
  "/another-path/another-resource":
    get:
      tags:
        - my-api
      operationId: getMyResource
      responses:
         ...
         [omitted]
         ...

有可能吗？

非常感谢您的时间。

Answer 1

您的问题被标记为openapi-generator，但似乎是关于OpenAPI规范的常见问题。

每个操作的操作ID必须唯一。规范defines operationId的Operation object部分为：

用于标识操作的唯一字符串。该ID在API中描述的所有操作中必须唯一。 operationId值<区分大小写。工具和库可以使用operationId唯一地标识一个操作，因此，建议遵循常见的编程命名约定。

粗体的“区分大小写”直接取自规范，但强调了将这些规范通过工具传递的一个很好的观点（这就是为什么它们必须唯一）。在openapi-generator中，我们使用operationId定义生成的输出中的方法或函数名称。许多语言不支持重载方法，有些甚至不支持非标准大小写（例如Go）。我们的工具将根据输出语言转换operationId，因此在这种情况下比规范更严格。如果您绝对需要重复的方法名称并且目标输出支持它，则可以创建一个自定义生成器并扩展处理操作的逻辑。